From 7139ae6dd3b88687723ecb45fa74ba9b1c0abc77 Mon Sep 17 00:00:00 2001 From: JezzDiego Date: Wed, 9 Apr 2025 11:16:36 -0300 Subject: [PATCH 1/7] docs: improve getMonthlyInfosByYear docs --- docs/docs.go | 18 +++---- docs/swagger.json | 18 +++---- docs/swagger.yaml | 32 ++++++++---- go.sum | 9 ---- papi/handlers.go | 122 +++++++++++++++++++++++----------------------- 5 files changed, 102 insertions(+), 97 deletions(-) diff --git a/docs/docs.go b/docs/docs.go index f933ff39..26fff573 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -576,7 +576,7 @@ const docTemplate = `{ }, "/v2/dados/{orgao}/{ano}": { "get": { - "description": "Busca os dados mensais de um órgão por ano", + "description": "Busca os dados mensais de um órgão específico trazendo informações de cada mês disponível para o ano informado, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice).", "produces": [ "application/json" ], @@ -587,14 +587,14 @@ const docTemplate = `{ "parameters": [ { "type": "integer", - "description": "Ano", + "description": "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018).", "name": "ano", "in": "path", "required": true }, { "type": "string", - "description": "Órgão", + "description": "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb", "name": "orgao", "in": "path", "required": true @@ -602,7 +602,7 @@ const docTemplate = `{ ], "responses": { "200": { - "description": "Requisição bem sucedida", + "description": "Requisição bem-sucedida com dados mensais", "schema": { "type": "array", "items": { @@ -627,7 +627,7 @@ const docTemplate = `{ }, "/v2/dados/{orgao}/{ano}/{mes}": { "get": { - "description": "Busca um dado mensal de um órgão", + "description": "Busca informações mensais de um órgão específico, incluindo dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice).", "produces": [ "application/json" ], @@ -638,21 +638,21 @@ const docTemplate = `{ "parameters": [ { "type": "integer", - "description": "Ano", + "description": "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018).", "name": "ano", "in": "path", "required": true }, { "type": "string", - "description": "Órgão", + "description": "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb", "name": "orgao", "in": "path", "required": true }, { "type": "integer", - "description": "Mês", + "description": "Mês para o qual os dados estão sendo solicitados (1-12).", "name": "mes", "in": "path", "required": true @@ -660,7 +660,7 @@ const docTemplate = `{ ], "responses": { "200": { - "description": "Requisição bem sucedida", + "description": "Requisição bem-sucedida com dados mensais", "schema": { "$ref": "#/definitions/papi.summaryzedMI" } diff --git a/docs/swagger.json b/docs/swagger.json index 19b0210c..5005ec2d 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -567,7 +567,7 @@ }, "/v2/dados/{orgao}/{ano}": { "get": { - "description": "Busca os dados mensais de um órgão por ano", + "description": "Busca os dados mensais de um órgão específico trazendo informações de cada mês disponível para o ano informado, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice).", "produces": [ "application/json" ], @@ -578,14 +578,14 @@ "parameters": [ { "type": "integer", - "description": "Ano", + "description": "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018).", "name": "ano", "in": "path", "required": true }, { "type": "string", - "description": "Órgão", + "description": "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb", "name": "orgao", "in": "path", "required": true @@ -593,7 +593,7 @@ ], "responses": { "200": { - "description": "Requisição bem sucedida", + "description": "Requisição bem-sucedida com dados mensais", "schema": { "type": "array", "items": { @@ -618,7 +618,7 @@ }, "/v2/dados/{orgao}/{ano}/{mes}": { "get": { - "description": "Busca um dado mensal de um órgão", + "description": "Busca informações mensais de um órgão específico, incluindo dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice).", "produces": [ "application/json" ], @@ -629,21 +629,21 @@ "parameters": [ { "type": "integer", - "description": "Ano", + "description": "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018).", "name": "ano", "in": "path", "required": true }, { "type": "string", - "description": "Órgão", + "description": "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb", "name": "orgao", "in": "path", "required": true }, { "type": "integer", - "description": "Mês", + "description": "Mês para o qual os dados estão sendo solicitados (1-12).", "name": "mes", "in": "path", "required": true @@ -651,7 +651,7 @@ ], "responses": { "200": { - "description": "Requisição bem sucedida", + "description": "Requisição bem-sucedida com dados mensais", "schema": { "$ref": "#/definitions/papi.summaryzedMI" } diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 33a4214d..236420e4 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -1033,15 +1033,22 @@ paths: - public_api /v2/dados/{orgao}/{ano}: get: - description: Busca os dados mensais de um órgão por ano + description: Busca os dados mensais de um órgão específico trazendo informações + de cada mês disponível para o ano informado, retornando dados de coleta (duração + da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração + base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, + quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados + de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice). operationId: GetMonthlyInfosByYear parameters: - - description: Ano + - description: Ano para o qual os dados estão sendo solicitados (dados disponíveis + a partir de 2018). in: path name: ano required: true type: integer - - description: Órgão + - description: 'Sigla do órgão para o qual os dados estão sendo solicitados. + Ex.: tjal, tjba, mppb' in: path name: orgao required: true @@ -1050,7 +1057,7 @@ paths: - application/json responses: "200": - description: Requisição bem sucedida + description: Requisição bem-sucedida com dados mensais schema: items: $ref: '#/definitions/papi.summaryzedMI' @@ -1067,20 +1074,27 @@ paths: - public_api /v2/dados/{orgao}/{ano}/{mes}: get: - description: Busca um dado mensal de um órgão + description: Busca informações mensais de um órgão específico, incluindo dados + de coleta (duração da coleta e dados do coletor), dados de remuneração (dos + membros ativos, remuneração base/salário, outras remunerações/benefícios, + descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas + identificadas/penduricalhos), metadados de completude e facilidade de acesso + e pontuação de transparência (https://dadosjusbr.org/indice). operationId: GetMonthlyInfo parameters: - - description: Ano + - description: Ano para o qual os dados estão sendo solicitados (dados disponíveis + a partir de 2018). in: path name: ano required: true type: integer - - description: Órgão + - description: 'Sigla do órgão para o qual os dados estão sendo solicitados. + Ex.: tjal, tjba, mppb' in: path name: orgao required: true type: string - - description: Mês + - description: Mês para o qual os dados estão sendo solicitados (1-12). in: path name: mes required: true @@ -1089,7 +1103,7 @@ paths: - application/json responses: "200": - description: Requisição bem sucedida + description: Requisição bem-sucedida com dados mensais schema: $ref: '#/definitions/papi.summaryzedMI' "400": diff --git a/go.sum b/go.sum index 53a8803f..ffd3f7fa 100644 --- a/go.sum +++ b/go.sum @@ -31,18 +31,9 @@ github.com/coreos/go-systemd v0.0.0-20190719114852-fd7a80b32e1f/go.mod h1:F5haX7 github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU= github.com/creack/pty v1.1.7/go.mod h1:lj5s0c3V2DBrqTV7llrYr5NG6My20zk30Fl46Y7DoTY= github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E= -github.com/dadosjusbr/datapackage v0.0.0-20230904162108-6e2264aafb68/go.mod h1:o1FghJC46mR+lgHcQWVve/q84/SAd0WVdYMcgq88BBU= github.com/dadosjusbr/datapackage v0.0.0-20240320203926-5f369dadd3a5/go.mod h1:xDZc4jX8VDOP7SFo793x0Q8gjUjuMSOmNEUG/wqLKAw= github.com/dadosjusbr/proto v0.0.0-20221212025627-91c60aa3cd12 h1:ufl8nbCEo6g2VHUbedGy0gYk9Sgrynf9rcnzuSw4TEg= github.com/dadosjusbr/proto v0.0.0-20221212025627-91c60aa3cd12/go.mod h1:gPA7VxjEmyez/xtln4qBj+tM1NO0/zcw3ryjxTRNSco= -github.com/dadosjusbr/storage v0.0.0-20240315221019-5da10c81ab80 h1:mo6k/MAl6aF662JFUYHxqCNvRkX8OXZN0DmQKJe55D4= -github.com/dadosjusbr/storage v0.0.0-20240315221019-5da10c81ab80/go.mod h1:PszGy6CDoG3kNLjIsCmwD3MAWED7xL7U/OWj7ajsiHc= -github.com/dadosjusbr/storage v0.0.0-20240514131514-43ac5da3ae8a h1:1LyzfsNzKgLjC4/cyQr+N724a4dcRCHB5yIauAnhhcI= -github.com/dadosjusbr/storage v0.0.0-20240514131514-43ac5da3ae8a/go.mod h1:rIM/dbZMdrMfVnZgNgRNRRtsxfhSMH8S8X7MZEeKkrQ= -github.com/dadosjusbr/storage v0.0.0-20240913213102-72765cc03b4e h1:RNcbmof3iPyJQNWbEPkNyKKffmQ8jkZa8QH/vZ5eJP0= -github.com/dadosjusbr/storage v0.0.0-20240913213102-72765cc03b4e/go.mod h1:rIM/dbZMdrMfVnZgNgRNRRtsxfhSMH8S8X7MZEeKkrQ= -github.com/dadosjusbr/storage v0.0.0-20240923172949-d3b675a3e292 h1:cgrdaqWjNN9enNcWPaPtqWFbxo1bLWz9C/Lxhke4WM4= -github.com/dadosjusbr/storage v0.0.0-20240923172949-d3b675a3e292/go.mod h1:rIM/dbZMdrMfVnZgNgRNRRtsxfhSMH8S8X7MZEeKkrQ= github.com/dadosjusbr/storage v0.0.0-20250212133431-b79ee305fcc5 h1:w3NNul4PA8lx2mvUfDrCGRouSsuncPc59dx3Zv6e84E= github.com/dadosjusbr/storage v0.0.0-20250212133431-b79ee305fcc5/go.mod h1:rIM/dbZMdrMfVnZgNgRNRRtsxfhSMH8S8X7MZEeKkrQ= github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= diff --git a/papi/handlers.go b/papi/handlers.go index f3b566e1..f5c7758a 100644 --- a/papi/handlers.go +++ b/papi/handlers.go @@ -39,14 +39,14 @@ func (h handler) V1GetAgencyById(c echo.Context) error { return c.JSON(http.StatusOK, agency) } -// @ID GetAgencyById -// @Tags public_api -// @Description Busca um órgão específico utilizando seu ID. -// @Produce json -// @Param orgao path string true "ID do órgão. Exemplos: tjal, tjba, mppb." -// @Success 200 {object} agency "Requisição bem sucedida." -// @Failure 404 {string} string "Órgão não encontrado." -// @Router /v2/orgao/{orgao} [get] +// @ID GetAgencyById +// @Tags public_api +// @Description Busca um órgão específico utilizando seu ID. +// @Produce json +// @Param orgao path string true "ID do órgão. Exemplos: tjal, tjba, mppb." +// @Success 200 {object} agency "Requisição bem sucedida." +// @Failure 404 {string} string "Órgão não encontrado." +// @Router /v2/orgao/{orgao} [get] func (h handler) V2GetAgencyById(c echo.Context) error { agencyName := c.Param("orgao") strAgency, err := h.client.Db.GetAgency(agencyName) @@ -92,13 +92,13 @@ func (h handler) V1GetAllAgencies(c echo.Context) error { return c.JSON(http.StatusOK, agencies) } -// @ID GetAllAgencies -// @Tags public_api -// @Description Busca todos os órgãos disponíveis. -// @Produce json -// @Success 200 {object} []agency "Requisição bem sucedida." -// @Failure 500 {string} string "Erro interno do servidor." -// @Router /v2/orgaos [get] +// @ID GetAllAgencies +// @Tags public_api +// @Description Busca todos os órgãos disponíveis. +// @Produce json +// @Success 200 {object} []agency "Requisição bem sucedida." +// @Failure 500 {string} string "Erro interno do servidor." +// @Router /v2/orgaos [get] func (h handler) V2GetAllAgencies(c echo.Context) error { strAgencies, err := h.client.Db.GetAllAgencies() if err != nil { @@ -264,17 +264,17 @@ func (h handler) GetMonthlyInfo(c echo.Context) error { return c.JSON(http.StatusOK, sumMI) } -// @ID GetMonthlyInfo -// @Tags public_api -// @Description Busca um dado mensal de um órgão -// @Produce json -// @Success 200 {object} summaryzedMI "Requisição bem sucedida" -// @Failure 400 {string} string "Parâmetros inválidos" -// @Failure 404 {string} string "Não existem dados para os parâmetros informados" -// @Param ano path int true "Ano" -// @Param orgao path string true "Órgão" -// @Param mes path int true "Mês" -// @Router /v2/dados/{orgao}/{ano}/{mes} [get] +// @ID GetMonthlyInfo +// @Tags public_api +// @Description Busca informações mensais de um órgão específico, incluindo dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice). +// @Produce json +// @Success 200 {object} summaryzedMI "Requisição bem-sucedida com dados mensais" +// @Failure 400 {string} string "Parâmetros inválidos" +// @Failure 404 {string} string "Não existem dados para os parâmetros informados" +// @Param ano path int true "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018)." +// @Param orgao path string true "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb" +// @Param mes path int true "Mês para o qual os dados estão sendo solicitados (1-12)." +// @Router /v2/dados/{orgao}/{ano}/{mes} [get] func (h handler) V2GetMonthlyInfo(c echo.Context) error { year, err := strconv.Atoi(c.Param("ano")) if err != nil { @@ -397,16 +397,16 @@ func (h handler) V2GetMonthlyInfo(c echo.Context) error { return c.JSON(http.StatusOK, sumMI) } -// @ID GetMonthlyInfosByYear -// @Tags public_api -// @Description Busca os dados mensais de um órgão por ano -// @Produce json -// @Success 200 {object} []summaryzedMI "Requisição bem sucedida" -// @Failure 400 {string} string "Parâmetros inválidos" -// @Failure 404 {string} string "Não existem dados para os parâmetros informados" -// @Param ano path int true "Ano" -// @Param orgao path string true "Órgão" -// @Router /v2/dados/{orgao}/{ano} [get] +// @ID GetMonthlyInfosByYear +// @Tags public_api +// @Description Busca os dados mensais de um órgão específico trazendo informações de cada mês disponível para o ano informado, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice). +// @Produce json +// @Success 200 {object} []summaryzedMI "Requisição bem-sucedida com dados mensais" +// @Failure 400 {string} string "Parâmetros inválidos" +// @Failure 404 {string} string "Não existem dados para os parâmetros informados" +// @Param ano path int true "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018)." +// @Param orgao path string true "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb" +// @Router /v2/dados/{orgao}/{ano} [get] func (h handler) GetMonthlyInfosByYear(c echo.Context) error { year, err := strconv.Atoi(c.Param("ano")) if err != nil { @@ -531,16 +531,16 @@ func (h handler) GetMonthlyInfosByYear(c echo.Context) error { return c.JSON(http.StatusOK, sumMI) } -// @ID GetAggregateIndexesWithParams -// @Tags public_api -// @Description Busca as informações de índices de um grupo ou órgão específico. -// @Produce json -// @Success 200 {object} []aggregateIndexes "Requisição bem sucedida." -// @Failure 400 {string} string "Requisição inválida." -// @Failure 500 {string} string "Erro interno do servidor." -// @Param param path string true "'grupo' ou 'orgao'" -// @Param valor path string true "Jurisdição ou ID do órgao" -// @Router /v2/indice/{param}/{valor} [get] +// @ID GetAggregateIndexesWithParams +// @Tags public_api +// @Description Busca as informações de índices de um grupo ou órgão específico. +// @Produce json +// @Success 200 {object} []aggregateIndexes "Requisição bem sucedida." +// @Failure 400 {string} string "Requisição inválida." +// @Failure 500 {string} string "Erro interno do servidor." +// @Param param path string true "'grupo' ou 'orgao'" +// @Param valor path string true "Jurisdição ou ID do órgao" +// @Router /v2/indice/{param}/{valor} [get] func (h handler) V2GetAggregateIndexesWithParams(c echo.Context) error { param := c.Param("param") valor := c.Param("valor") @@ -688,13 +688,13 @@ func (h handler) V2GetAggregateIndexesWithParams(c echo.Context) error { return c.JSON(http.StatusOK, aggregate) } -// @ID GetAggregateIndexes -// @Tags public_api -// @Description Busca as informações de índices de todos os órgãos. -// @Produce json -// @Success 200 {object} []aggregateIndexesByGroup "Requisição bem sucedida." -// @Failure 500 {string} string "Erro interno do servidor." -// @Router /v2/indice [get] +// @ID GetAggregateIndexes +// @Tags public_api +// @Description Busca as informações de índices de todos os órgãos. +// @Produce json +// @Success 200 {object} []aggregateIndexesByGroup "Requisição bem sucedida." +// @Failure 500 {string} string "Erro interno do servidor." +// @Router /v2/indice [get] func (h handler) V2GetAggregateIndexes(c echo.Context) error { agregado := c.QueryParam("agregado") detalhe := c.QueryParam("detalhe") @@ -798,14 +798,14 @@ func (h handler) V2GetAggregateIndexes(c echo.Context) error { return c.JSON(http.StatusOK, dados) } -// @ID GetAllAgencyInformation -// @Tags public_api -// @Description Busca todas as informações de um órgão específico. -// @Produce json -// @Success 200 {object} allAgencyInformation "Requisição bem sucedida." -// @Failure 400 {string} string "Requisição inválida." -// @Param orgao path string true "órgão" -// @Router /v2/dados/{orgao} [get] +// @ID GetAllAgencyInformation +// @Tags public_api +// @Description Busca todas as informações de um órgão específico. +// @Produce json +// @Success 200 {object} allAgencyInformation "Requisição bem sucedida." +// @Failure 400 {string} string "Requisição inválida." +// @Param orgao path string true "órgão" +// @Router /v2/dados/{orgao} [get] func (h handler) V2GetAllAgencyInformation(c echo.Context) error { agency := strings.ToLower(c.Param("orgao")) From 96026a5f8e46cbf34db1f9acff4935e777dad64f Mon Sep 17 00:00:00 2001 From: JezzDiego Date: Wed, 9 Apr 2025 19:41:53 -0300 Subject: [PATCH 2/7] docs: improve and add new endpoits to swagger docs --- docs/docs.go | 191 +++++++++++++++++++++++++++++++++++++++++++--- docs/swagger.json | 191 +++++++++++++++++++++++++++++++++++++++++++--- docs/swagger.yaml | 190 ++++++++++++++++++++++++++++++++++++++++++--- papi/handlers.go | 81 +++++++++++++++----- 4 files changed, 605 insertions(+), 48 deletions(-) diff --git a/docs/docs.go b/docs/docs.go index 26fff573..0076da96 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -541,7 +541,7 @@ const docTemplate = `{ }, "/v2/dados/{orgao}": { "get": { - "description": "Busca todas as informações de um órgão específico.", + "description": "Busca todos os dados de um órgão específico trazendo informações de cada mês disponível para cada ano disponível a partir de 2018, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice).", "produces": [ "application/json" ], @@ -552,7 +552,7 @@ const docTemplate = `{ "parameters": [ { "type": "string", - "description": "órgão", + "description": "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb", "name": "orgao", "in": "path", "required": true @@ -682,7 +682,7 @@ const docTemplate = `{ }, "/v2/indice": { "get": { - "description": "Busca as informações de índices de todos os órgãos.", + "description": "Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) de todos os órgãos, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses) organizando-os por jurisdição: Justiça Estadual, Ministérios Públicos, Justiça do Trabalho, Justiça Militar, Justiça Federal, Justiça Eleitoral, Justiça Superior e Conselhos de Justiça.", "produces": [ "application/json" ], @@ -690,6 +690,20 @@ const docTemplate = `{ "public_api" ], "operationId": "GetAggregateIndexes", + "parameters": [ + { + "type": "boolean", + "description": "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês.", + "name": "agregado", + "in": "query" + }, + { + "type": "boolean", + "description": "Define se os metadados utilizados para calcular o índice serão retornados ou não.", + "name": "detalhe", + "in": "query" + } + ], "responses": { "200": { "description": "Requisição bem sucedida.", @@ -711,7 +725,7 @@ const docTemplate = `{ }, "/v2/indice/{param}/{valor}": { "get": { - "description": "Busca as informações de índices de um grupo ou órgão específico.", + "description": "Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, justica-eleitoral, justica-superior e conselhos-de-justica.", "produces": [ "application/json" ], @@ -722,17 +736,176 @@ const docTemplate = `{ "parameters": [ { "type": "string", - "description": "'grupo' ou 'orgao'", + "description": "'grupo' para pesquisar por jurisdição ou 'orgao' para pesquisar pela sigla do órgão", "name": "param", "in": "path", "required": true }, { "type": "string", - "description": "Jurisdição ou ID do órgao", + "description": "Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, etc.", "name": "valor", "in": "path", "required": true + }, + { + "type": "boolean", + "description": "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês.", + "name": "agregado", + "in": "query" + }, + { + "type": "boolean", + "description": "Define se os metadados utilizados para calcular o índice serão retornados ou não.", + "name": "detalhe", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Requisição bem sucedida.", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/papi.aggregateIndexes" + } + } + }, + "400": { + "description": "Requisição inválida.", + "schema": { + "type": "string" + } + }, + "500": { + "description": "Erro interno do servidor.", + "schema": { + "type": "string" + } + } + } + } + }, + "/v2/indice/{param}/{valor}/{ano}": { + "get": { + "description": "Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, justica-eleitoral, justica-superior e conselhos-de-justica.", + "produces": [ + "application/json" + ], + "tags": [ + "public_api" + ], + "operationId": "GetAggregateIndexesWithParamsByYear", + "parameters": [ + { + "type": "string", + "description": "'grupo' para pesquisar por jurisdição ou 'orgao' para pesquisar pela sigla do órgão", + "name": "param", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, etc.", + "name": "valor", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018).", + "name": "ano", + "in": "path", + "required": true + }, + { + "type": "boolean", + "description": "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês.", + "name": "agregado", + "in": "query" + }, + { + "type": "boolean", + "description": "Define se os metadados utilizados para calcular o índice serão retornados ou não.", + "name": "detalhe", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Requisição bem sucedida.", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/papi.aggregateIndexes" + } + } + }, + "400": { + "description": "Requisição inválida.", + "schema": { + "type": "string" + } + }, + "500": { + "description": "Erro interno do servidor.", + "schema": { + "type": "string" + } + } + } + } + }, + "/v2/indice/{param}/{valor}/{ano}/{mes}": { + "get": { + "description": "Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, justica-eleitoral, justica-superior e conselhos-de-justica.", + "produces": [ + "application/json" + ], + "tags": [ + "public_api" + ], + "operationId": "GetAggregateIndexesWithParamsByYearAndMonth", + "parameters": [ + { + "type": "string", + "description": "'grupo' para pesquisar por jurisdição ou 'orgao' para pesquisar pela sigla do órgão", + "name": "param", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, etc.", + "name": "valor", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018).", + "name": "ano", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "Mês para o qual os dados estão sendo solicitados (1-12).", + "name": "mes", + "in": "path", + "required": true + }, + { + "type": "boolean", + "description": "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês.", + "name": "agregado", + "in": "query" + }, + { + "type": "boolean", + "description": "Define se os metadados utilizados para calcular o índice serão retornados ou não.", + "name": "detalhe", + "in": "query" } ], "responses": { @@ -762,7 +935,7 @@ const docTemplate = `{ }, "/v2/orgao/{orgao}": { "get": { - "description": "Busca um órgão específico utilizando seu ID.", + "description": "Busca informações gerais de um órgão como nome completo, jurisdição, tipo de entidade, uf do órgão, perfil do twitter e link para a ouvidoria. Se o órgão informado não for coletado pelo DadosJusBr, um objeto com o motivo da coleta não ser automatizada também será retornado. Não inclue informações de remuneração.", "produces": [ "application/json" ], @@ -773,7 +946,7 @@ const docTemplate = `{ "parameters": [ { "type": "string", - "description": "ID do órgão. Exemplos: tjal, tjba, mppb.", + "description": "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb.", "name": "orgao", "in": "path", "required": true @@ -797,7 +970,7 @@ const docTemplate = `{ }, "/v2/orgaos": { "get": { - "description": "Busca todos os órgãos disponíveis.", + "description": "Busca informações gerais de todos os órgão como nome completo, jurisdição, tipo de entidade, uf do órgão, perfil do twitter e link para a ouvidoria. Se algum órgão da lista não for coletado pelo DadosJusBr, um objeto com o motivo da coleta não ser automatizada também será retornado. Não inclue informações de remuneração.", "produces": [ "application/json" ], diff --git a/docs/swagger.json b/docs/swagger.json index 5005ec2d..9870f399 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -532,7 +532,7 @@ }, "/v2/dados/{orgao}": { "get": { - "description": "Busca todas as informações de um órgão específico.", + "description": "Busca todos os dados de um órgão específico trazendo informações de cada mês disponível para cada ano disponível a partir de 2018, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice).", "produces": [ "application/json" ], @@ -543,7 +543,7 @@ "parameters": [ { "type": "string", - "description": "órgão", + "description": "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb", "name": "orgao", "in": "path", "required": true @@ -673,7 +673,7 @@ }, "/v2/indice": { "get": { - "description": "Busca as informações de índices de todos os órgãos.", + "description": "Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) de todos os órgãos, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses) organizando-os por jurisdição: Justiça Estadual, Ministérios Públicos, Justiça do Trabalho, Justiça Militar, Justiça Federal, Justiça Eleitoral, Justiça Superior e Conselhos de Justiça.", "produces": [ "application/json" ], @@ -681,6 +681,20 @@ "public_api" ], "operationId": "GetAggregateIndexes", + "parameters": [ + { + "type": "boolean", + "description": "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês.", + "name": "agregado", + "in": "query" + }, + { + "type": "boolean", + "description": "Define se os metadados utilizados para calcular o índice serão retornados ou não.", + "name": "detalhe", + "in": "query" + } + ], "responses": { "200": { "description": "Requisição bem sucedida.", @@ -702,7 +716,7 @@ }, "/v2/indice/{param}/{valor}": { "get": { - "description": "Busca as informações de índices de um grupo ou órgão específico.", + "description": "Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, justica-eleitoral, justica-superior e conselhos-de-justica.", "produces": [ "application/json" ], @@ -713,17 +727,176 @@ "parameters": [ { "type": "string", - "description": "'grupo' ou 'orgao'", + "description": "'grupo' para pesquisar por jurisdição ou 'orgao' para pesquisar pela sigla do órgão", "name": "param", "in": "path", "required": true }, { "type": "string", - "description": "Jurisdição ou ID do órgao", + "description": "Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, etc.", "name": "valor", "in": "path", "required": true + }, + { + "type": "boolean", + "description": "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês.", + "name": "agregado", + "in": "query" + }, + { + "type": "boolean", + "description": "Define se os metadados utilizados para calcular o índice serão retornados ou não.", + "name": "detalhe", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Requisição bem sucedida.", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/papi.aggregateIndexes" + } + } + }, + "400": { + "description": "Requisição inválida.", + "schema": { + "type": "string" + } + }, + "500": { + "description": "Erro interno do servidor.", + "schema": { + "type": "string" + } + } + } + } + }, + "/v2/indice/{param}/{valor}/{ano}": { + "get": { + "description": "Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, justica-eleitoral, justica-superior e conselhos-de-justica.", + "produces": [ + "application/json" + ], + "tags": [ + "public_api" + ], + "operationId": "GetAggregateIndexesWithParamsByYear", + "parameters": [ + { + "type": "string", + "description": "'grupo' para pesquisar por jurisdição ou 'orgao' para pesquisar pela sigla do órgão", + "name": "param", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, etc.", + "name": "valor", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018).", + "name": "ano", + "in": "path", + "required": true + }, + { + "type": "boolean", + "description": "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês.", + "name": "agregado", + "in": "query" + }, + { + "type": "boolean", + "description": "Define se os metadados utilizados para calcular o índice serão retornados ou não.", + "name": "detalhe", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Requisição bem sucedida.", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/papi.aggregateIndexes" + } + } + }, + "400": { + "description": "Requisição inválida.", + "schema": { + "type": "string" + } + }, + "500": { + "description": "Erro interno do servidor.", + "schema": { + "type": "string" + } + } + } + } + }, + "/v2/indice/{param}/{valor}/{ano}/{mes}": { + "get": { + "description": "Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, justica-eleitoral, justica-superior e conselhos-de-justica.", + "produces": [ + "application/json" + ], + "tags": [ + "public_api" + ], + "operationId": "GetAggregateIndexesWithParamsByYearAndMonth", + "parameters": [ + { + "type": "string", + "description": "'grupo' para pesquisar por jurisdição ou 'orgao' para pesquisar pela sigla do órgão", + "name": "param", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, etc.", + "name": "valor", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018).", + "name": "ano", + "in": "path", + "required": true + }, + { + "type": "integer", + "description": "Mês para o qual os dados estão sendo solicitados (1-12).", + "name": "mes", + "in": "path", + "required": true + }, + { + "type": "boolean", + "description": "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês.", + "name": "agregado", + "in": "query" + }, + { + "type": "boolean", + "description": "Define se os metadados utilizados para calcular o índice serão retornados ou não.", + "name": "detalhe", + "in": "query" } ], "responses": { @@ -753,7 +926,7 @@ }, "/v2/orgao/{orgao}": { "get": { - "description": "Busca um órgão específico utilizando seu ID.", + "description": "Busca informações gerais de um órgão como nome completo, jurisdição, tipo de entidade, uf do órgão, perfil do twitter e link para a ouvidoria. Se o órgão informado não for coletado pelo DadosJusBr, um objeto com o motivo da coleta não ser automatizada também será retornado. Não inclue informações de remuneração.", "produces": [ "application/json" ], @@ -764,7 +937,7 @@ "parameters": [ { "type": "string", - "description": "ID do órgão. Exemplos: tjal, tjba, mppb.", + "description": "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb.", "name": "orgao", "in": "path", "required": true @@ -788,7 +961,7 @@ }, "/v2/orgaos": { "get": { - "description": "Busca todos os órgãos disponíveis.", + "description": "Busca informações gerais de todos os órgão como nome completo, jurisdição, tipo de entidade, uf do órgão, perfil do twitter e link para a ouvidoria. Se algum órgão da lista não for coletado pelo DadosJusBr, um objeto com o motivo da coleta não ser automatizada também será retornado. Não inclue informações de remuneração.", "produces": [ "application/json" ], diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 236420e4..1f136497 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -1010,10 +1010,17 @@ paths: - ui_api /v2/dados/{orgao}: get: - description: Busca todas as informações de um órgão específico. + description: Busca todos os dados de um órgão específico trazendo informações + de cada mês disponível para cada ano disponível a partir de 2018, retornando + dados de coleta (duração da coleta e dados do coletor), dados de remuneração + (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, + descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas + identificadas/penduricalhos), metadados de completude e facilidade de acesso + e pontuação de transparência (https://dadosjusbr.org/indice). operationId: GetAllAgencyInformation parameters: - - description: órgão + - description: 'Sigla do órgão para o qual os dados estão sendo solicitados. + Ex.: tjal, tjba, mppb' in: path name: orgao required: true @@ -1118,8 +1125,25 @@ paths: - public_api /v2/indice: get: - description: Busca as informações de índices de todos os órgãos. + description: 'Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) + de todos os órgãos, trazendo o detalhamento (granularidade mensal), os metadados + (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado + do Índice de Trasparência médio do órgão ao longo dos meses) organizando-os + por jurisdição: Justiça Estadual, Ministérios Públicos, Justiça do Trabalho, + Justiça Militar, Justiça Federal, Justiça Eleitoral, Justiça Superior e Conselhos + de Justiça.' operationId: GetAggregateIndexes + parameters: + - description: Alterna entre o Índice de Transparência geral de todos os órgãos + (true) ou o detalhamento do índice de cada órgão mês a mês. + in: query + name: agregado + type: boolean + - description: Define se os metadados utilizados para calcular o índice serão + retornados ou não. + in: query + name: detalhe + type: boolean produces: - application/json responses: @@ -1137,19 +1161,158 @@ paths: - public_api /v2/indice/{param}/{valor}: get: - description: Busca as informações de índices de um grupo ou órgão específico. + description: 'Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) + do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo + o detalhamento (granularidade mensal), os metadados (critérios de avaliação + do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência + médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, + ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, + justica-eleitoral, justica-superior e conselhos-de-justica.' operationId: GetAggregateIndexesWithParams parameters: - - description: '''grupo'' ou ''orgao''' + - description: '''grupo'' para pesquisar por jurisdição ou ''orgao'' para pesquisar + pela sigla do órgão' in: path name: param required: true type: string - - description: Jurisdição ou ID do órgao + - description: 'Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, + etc.' in: path name: valor required: true type: string + - description: Alterna entre o Índice de Transparência geral de todos os órgãos + (true) ou o detalhamento do índice de cada órgão mês a mês. + in: query + name: agregado + type: boolean + - description: Define se os metadados utilizados para calcular o índice serão + retornados ou não. + in: query + name: detalhe + type: boolean + produces: + - application/json + responses: + "200": + description: Requisição bem sucedida. + schema: + items: + $ref: '#/definitions/papi.aggregateIndexes' + type: array + "400": + description: Requisição inválida. + schema: + type: string + "500": + description: Erro interno do servidor. + schema: + type: string + tags: + - public_api + /v2/indice/{param}/{valor}/{ano}: + get: + description: 'Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) + do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo + o detalhamento (granularidade mensal), os metadados (critérios de avaliação + do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência + médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, + ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, + justica-eleitoral, justica-superior e conselhos-de-justica.' + operationId: GetAggregateIndexesWithParamsByYear + parameters: + - description: '''grupo'' para pesquisar por jurisdição ou ''orgao'' para pesquisar + pela sigla do órgão' + in: path + name: param + required: true + type: string + - description: 'Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, + etc.' + in: path + name: valor + required: true + type: string + - description: Ano para o qual os dados estão sendo solicitados (dados disponíveis + a partir de 2018). + in: path + name: ano + required: true + type: integer + - description: Alterna entre o Índice de Transparência geral de todos os órgãos + (true) ou o detalhamento do índice de cada órgão mês a mês. + in: query + name: agregado + type: boolean + - description: Define se os metadados utilizados para calcular o índice serão + retornados ou não. + in: query + name: detalhe + type: boolean + produces: + - application/json + responses: + "200": + description: Requisição bem sucedida. + schema: + items: + $ref: '#/definitions/papi.aggregateIndexes' + type: array + "400": + description: Requisição inválida. + schema: + type: string + "500": + description: Erro interno do servidor. + schema: + type: string + tags: + - public_api + /v2/indice/{param}/{valor}/{ano}/{mes}: + get: + description: 'Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) + do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo + o detalhamento (granularidade mensal), os metadados (critérios de avaliação + do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência + médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, + ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, + justica-eleitoral, justica-superior e conselhos-de-justica.' + operationId: GetAggregateIndexesWithParamsByYearAndMonth + parameters: + - description: '''grupo'' para pesquisar por jurisdição ou ''orgao'' para pesquisar + pela sigla do órgão' + in: path + name: param + required: true + type: string + - description: 'Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, + etc.' + in: path + name: valor + required: true + type: string + - description: Ano para o qual os dados estão sendo solicitados (dados disponíveis + a partir de 2018). + in: path + name: ano + required: true + type: integer + - description: Mês para o qual os dados estão sendo solicitados (1-12). + in: path + name: mes + required: true + type: integer + - description: Alterna entre o Índice de Transparência geral de todos os órgãos + (true) ou o detalhamento do índice de cada órgão mês a mês. + in: query + name: agregado + type: boolean + - description: Define se os metadados utilizados para calcular o índice serão + retornados ou não. + in: query + name: detalhe + type: boolean produces: - application/json responses: @@ -1171,10 +1334,15 @@ paths: - public_api /v2/orgao/{orgao}: get: - description: Busca um órgão específico utilizando seu ID. + description: Busca informações gerais de um órgão como nome completo, jurisdição, + tipo de entidade, uf do órgão, perfil do twitter e link para a ouvidoria. + Se o órgão informado não for coletado pelo DadosJusBr, um objeto com o motivo + da coleta não ser automatizada também será retornado. Não inclue informações + de remuneração. operationId: GetAgencyById parameters: - - description: 'ID do órgão. Exemplos: tjal, tjba, mppb.' + - description: 'Sigla do órgão para o qual os dados estão sendo solicitados. + Ex.: tjal, tjba, mppb.' in: path name: orgao required: true @@ -1194,7 +1362,11 @@ paths: - public_api /v2/orgaos: get: - description: Busca todos os órgãos disponíveis. + description: Busca informações gerais de todos os órgão como nome completo, + jurisdição, tipo de entidade, uf do órgão, perfil do twitter e link para a + ouvidoria. Se algum órgão da lista não for coletado pelo DadosJusBr, um objeto + com o motivo da coleta não ser automatizada também será retornado. Não inclue + informações de remuneração. operationId: GetAllAgencies produces: - application/json diff --git a/papi/handlers.go b/papi/handlers.go index f5c7758a..26c60836 100644 --- a/papi/handlers.go +++ b/papi/handlers.go @@ -41,9 +41,9 @@ func (h handler) V1GetAgencyById(c echo.Context) error { // @ID GetAgencyById // @Tags public_api -// @Description Busca um órgão específico utilizando seu ID. +// @Description Busca informações gerais de um órgão como nome completo, jurisdição, tipo de entidade, uf do órgão, perfil do twitter e link para a ouvidoria. Se o órgão informado não for coletado pelo DadosJusBr, um objeto com o motivo da coleta não ser automatizada também será retornado. Não inclue informações de remuneração. // @Produce json -// @Param orgao path string true "ID do órgão. Exemplos: tjal, tjba, mppb." +// @Param orgao path string true "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb." // @Success 200 {object} agency "Requisição bem sucedida." // @Failure 404 {string} string "Órgão não encontrado." // @Router /v2/orgao/{orgao} [get] @@ -94,7 +94,7 @@ func (h handler) V1GetAllAgencies(c echo.Context) error { // @ID GetAllAgencies // @Tags public_api -// @Description Busca todos os órgãos disponíveis. +// @Description Busca informações gerais de todos os órgão como nome completo, jurisdição, tipo de entidade, uf do órgão, perfil do twitter e link para a ouvidoria. Se algum órgão da lista não for coletado pelo DadosJusBr, um objeto com o motivo da coleta não ser automatizada também será retornado. Não inclue informações de remuneração. // @Produce json // @Success 200 {object} []agency "Requisição bem sucedida." // @Failure 500 {string} string "Erro interno do servidor." @@ -397,16 +397,16 @@ func (h handler) V2GetMonthlyInfo(c echo.Context) error { return c.JSON(http.StatusOK, sumMI) } -// @ID GetMonthlyInfosByYear -// @Tags public_api -// @Description Busca os dados mensais de um órgão específico trazendo informações de cada mês disponível para o ano informado, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice). -// @Produce json -// @Success 200 {object} []summaryzedMI "Requisição bem-sucedida com dados mensais" -// @Failure 400 {string} string "Parâmetros inválidos" -// @Failure 404 {string} string "Não existem dados para os parâmetros informados" -// @Param ano path int true "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018)." -// @Param orgao path string true "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb" -// @Router /v2/dados/{orgao}/{ano} [get] +// @ID GetMonthlyInfosByYear +// @Tags public_api +// @Description Busca os dados mensais de um órgão específico trazendo informações de cada mês disponível para o ano informado, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice). +// @Produce json +// @Success 200 {object} []summaryzedMI "Requisição bem-sucedida com dados mensais" +// @Failure 400 {string} string "Parâmetros inválidos" +// @Failure 404 {string} string "Não existem dados para os parâmetros informados" +// @Param ano path int true "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018)." +// @Param orgao path string true "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb" +// @Router /v2/dados/{orgao}/{ano} [get] func (h handler) GetMonthlyInfosByYear(c echo.Context) error { year, err := strconv.Atoi(c.Param("ano")) if err != nil { @@ -533,14 +533,16 @@ func (h handler) GetMonthlyInfosByYear(c echo.Context) error { // @ID GetAggregateIndexesWithParams // @Tags public_api -// @Description Busca as informações de índices de um grupo ou órgão específico. +// @Description Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, justica-eleitoral, justica-superior e conselhos-de-justica. // @Produce json // @Success 200 {object} []aggregateIndexes "Requisição bem sucedida." // @Failure 400 {string} string "Requisição inválida." // @Failure 500 {string} string "Erro interno do servidor." -// @Param param path string true "'grupo' ou 'orgao'" -// @Param valor path string true "Jurisdição ou ID do órgao" -// @Router /v2/indice/{param}/{valor} [get] +// @Param param path string true "'grupo' para pesquisar por jurisdição ou 'orgao' para pesquisar pela sigla do órgão" +// @Param valor path string true "Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, etc." +// @Param agregado query boolean false "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês." +// @Param detalhe query boolean false "Define se os metadados utilizados para calcular o índice serão retornados ou não." +// @Router /v2/indice/{param}/{valor} [get] func (h handler) V2GetAggregateIndexesWithParams(c echo.Context) error { param := c.Param("param") valor := c.Param("valor") @@ -688,13 +690,50 @@ func (h handler) V2GetAggregateIndexesWithParams(c echo.Context) error { return c.JSON(http.StatusOK, aggregate) } +// @ID GetAggregateIndexesWithParamsByYear +// @Tags public_api +// @Description Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, justica-eleitoral, justica-superior e conselhos-de-justica. +// @Produce json +// @Success 200 {object} []aggregateIndexes "Requisição bem sucedida." +// @Failure 400 {string} string "Requisição inválida." +// @Failure 500 {string} string "Erro interno do servidor." +// @Param param path string true "'grupo' para pesquisar por jurisdição ou 'orgao' para pesquisar pela sigla do órgão" +// @Param valor path string true "Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, etc." +// @Param ano path int true "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018)." +// @Param agregado query boolean false "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês." +// @Param detalhe query boolean false "Define se os metadados utilizados para calcular o índice serão retornados ou não." +// @Router /v2/indice/{param}/{valor}/{ano} [get] +func (h handler) V2GetAggregateIndexesWithParamsByYear(c echo.Context) error { + return h.V2GetAggregateIndexesWithParams(c) +} + +// @ID GetAggregateIndexesWithParamsByYearAndMonth +// @Tags public_api +// @Description Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, justica-eleitoral, justica-superior e conselhos-de-justica. +// @Produce json +// @Success 200 {object} []aggregateIndexes "Requisição bem sucedida." +// @Failure 400 {string} string "Requisição inválida." +// @Failure 500 {string} string "Erro interno do servidor." +// @Param param path string true "'grupo' para pesquisar por jurisdição ou 'orgao' para pesquisar pela sigla do órgão" +// @Param valor path string true "Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, etc." +// @Param ano path int true "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018)." +// @Param mes path int true "Mês para o qual os dados estão sendo solicitados (1-12)." +// @Param agregado query boolean false "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês." +// @Param detalhe query boolean false "Define se os metadados utilizados para calcular o índice serão retornados ou não." +// @Router /v2/indice/{param}/{valor}/{ano}/{mes} [get] +func (h handler) V2GetAggregateIndexesWithParamsByYearAndMonth(c echo.Context) error { + return h.V2GetAggregateIndexesWithParams(c) +} + // @ID GetAggregateIndexes // @Tags public_api -// @Description Busca as informações de índices de todos os órgãos. +// @Description Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) de todos os órgãos, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses) organizando-os por jurisdição: Justiça Estadual, Ministérios Públicos, Justiça do Trabalho, Justiça Militar, Justiça Federal, Justiça Eleitoral, Justiça Superior e Conselhos de Justiça. // @Produce json +// @Param agregado query boolean false "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês." +// @Param detalhe query boolean false "Define se os metadados utilizados para calcular o índice serão retornados ou não." // @Success 200 {object} []aggregateIndexesByGroup "Requisição bem sucedida." // @Failure 500 {string} string "Erro interno do servidor." -// @Router /v2/indice [get] +// @Router /v2/indice [get] func (h handler) V2GetAggregateIndexes(c echo.Context) error { agregado := c.QueryParam("agregado") detalhe := c.QueryParam("detalhe") @@ -800,11 +839,11 @@ func (h handler) V2GetAggregateIndexes(c echo.Context) error { // @ID GetAllAgencyInformation // @Tags public_api -// @Description Busca todas as informações de um órgão específico. +// @Description Busca todos os dados de um órgão específico trazendo informações de cada mês disponível para cada ano disponível a partir de 2018, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice). // @Produce json // @Success 200 {object} allAgencyInformation "Requisição bem sucedida." // @Failure 400 {string} string "Requisição inválida." -// @Param orgao path string true "órgão" +// @Param orgao path string true "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb" // @Router /v2/dados/{orgao} [get] func (h handler) V2GetAllAgencyInformation(c echo.Context) error { agency := strings.ToLower(c.Param("orgao")) From 1e1d5ab64dc3bb58f35d7410d79a969b5d8fe7e6 Mon Sep 17 00:00:00 2001 From: JezzDiego Date: Wed, 9 Apr 2025 19:42:19 -0300 Subject: [PATCH 3/7] docs: format docs --- papi/handlers.go | 184 +++++++++++++++++++++++------------------------ 1 file changed, 92 insertions(+), 92 deletions(-) diff --git a/papi/handlers.go b/papi/handlers.go index 26c60836..6e8763e7 100644 --- a/papi/handlers.go +++ b/papi/handlers.go @@ -39,14 +39,14 @@ func (h handler) V1GetAgencyById(c echo.Context) error { return c.JSON(http.StatusOK, agency) } -// @ID GetAgencyById -// @Tags public_api -// @Description Busca informações gerais de um órgão como nome completo, jurisdição, tipo de entidade, uf do órgão, perfil do twitter e link para a ouvidoria. Se o órgão informado não for coletado pelo DadosJusBr, um objeto com o motivo da coleta não ser automatizada também será retornado. Não inclue informações de remuneração. -// @Produce json -// @Param orgao path string true "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb." -// @Success 200 {object} agency "Requisição bem sucedida." -// @Failure 404 {string} string "Órgão não encontrado." -// @Router /v2/orgao/{orgao} [get] +// @ID GetAgencyById +// @Tags public_api +// @Description Busca informações gerais de um órgão como nome completo, jurisdição, tipo de entidade, uf do órgão, perfil do twitter e link para a ouvidoria. Se o órgão informado não for coletado pelo DadosJusBr, um objeto com o motivo da coleta não ser automatizada também será retornado. Não inclue informações de remuneração. +// @Produce json +// @Param orgao path string true "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb." +// @Success 200 {object} agency "Requisição bem sucedida." +// @Failure 404 {string} string "Órgão não encontrado." +// @Router /v2/orgao/{orgao} [get] func (h handler) V2GetAgencyById(c echo.Context) error { agencyName := c.Param("orgao") strAgency, err := h.client.Db.GetAgency(agencyName) @@ -92,13 +92,13 @@ func (h handler) V1GetAllAgencies(c echo.Context) error { return c.JSON(http.StatusOK, agencies) } -// @ID GetAllAgencies -// @Tags public_api -// @Description Busca informações gerais de todos os órgão como nome completo, jurisdição, tipo de entidade, uf do órgão, perfil do twitter e link para a ouvidoria. Se algum órgão da lista não for coletado pelo DadosJusBr, um objeto com o motivo da coleta não ser automatizada também será retornado. Não inclue informações de remuneração. -// @Produce json -// @Success 200 {object} []agency "Requisição bem sucedida." -// @Failure 500 {string} string "Erro interno do servidor." -// @Router /v2/orgaos [get] +// @ID GetAllAgencies +// @Tags public_api +// @Description Busca informações gerais de todos os órgão como nome completo, jurisdição, tipo de entidade, uf do órgão, perfil do twitter e link para a ouvidoria. Se algum órgão da lista não for coletado pelo DadosJusBr, um objeto com o motivo da coleta não ser automatizada também será retornado. Não inclue informações de remuneração. +// @Produce json +// @Success 200 {object} []agency "Requisição bem sucedida." +// @Failure 500 {string} string "Erro interno do servidor." +// @Router /v2/orgaos [get] func (h handler) V2GetAllAgencies(c echo.Context) error { strAgencies, err := h.client.Db.GetAllAgencies() if err != nil { @@ -264,17 +264,17 @@ func (h handler) GetMonthlyInfo(c echo.Context) error { return c.JSON(http.StatusOK, sumMI) } -// @ID GetMonthlyInfo -// @Tags public_api -// @Description Busca informações mensais de um órgão específico, incluindo dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice). -// @Produce json -// @Success 200 {object} summaryzedMI "Requisição bem-sucedida com dados mensais" -// @Failure 400 {string} string "Parâmetros inválidos" -// @Failure 404 {string} string "Não existem dados para os parâmetros informados" -// @Param ano path int true "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018)." -// @Param orgao path string true "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb" -// @Param mes path int true "Mês para o qual os dados estão sendo solicitados (1-12)." -// @Router /v2/dados/{orgao}/{ano}/{mes} [get] +// @ID GetMonthlyInfo +// @Tags public_api +// @Description Busca informações mensais de um órgão específico, incluindo dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice). +// @Produce json +// @Success 200 {object} summaryzedMI "Requisição bem-sucedida com dados mensais" +// @Failure 400 {string} string "Parâmetros inválidos" +// @Failure 404 {string} string "Não existem dados para os parâmetros informados" +// @Param ano path int true "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018)." +// @Param orgao path string true "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb" +// @Param mes path int true "Mês para o qual os dados estão sendo solicitados (1-12)." +// @Router /v2/dados/{orgao}/{ano}/{mes} [get] func (h handler) V2GetMonthlyInfo(c echo.Context) error { year, err := strconv.Atoi(c.Param("ano")) if err != nil { @@ -397,16 +397,16 @@ func (h handler) V2GetMonthlyInfo(c echo.Context) error { return c.JSON(http.StatusOK, sumMI) } -// @ID GetMonthlyInfosByYear -// @Tags public_api -// @Description Busca os dados mensais de um órgão específico trazendo informações de cada mês disponível para o ano informado, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice). -// @Produce json -// @Success 200 {object} []summaryzedMI "Requisição bem-sucedida com dados mensais" -// @Failure 400 {string} string "Parâmetros inválidos" -// @Failure 404 {string} string "Não existem dados para os parâmetros informados" -// @Param ano path int true "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018)." -// @Param orgao path string true "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb" -// @Router /v2/dados/{orgao}/{ano} [get] +// @ID GetMonthlyInfosByYear +// @Tags public_api +// @Description Busca os dados mensais de um órgão específico trazendo informações de cada mês disponível para o ano informado, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice). +// @Produce json +// @Success 200 {object} []summaryzedMI "Requisição bem-sucedida com dados mensais" +// @Failure 400 {string} string "Parâmetros inválidos" +// @Failure 404 {string} string "Não existem dados para os parâmetros informados" +// @Param ano path int true "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018)." +// @Param orgao path string true "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb" +// @Router /v2/dados/{orgao}/{ano} [get] func (h handler) GetMonthlyInfosByYear(c echo.Context) error { year, err := strconv.Atoi(c.Param("ano")) if err != nil { @@ -531,18 +531,18 @@ func (h handler) GetMonthlyInfosByYear(c echo.Context) error { return c.JSON(http.StatusOK, sumMI) } -// @ID GetAggregateIndexesWithParams -// @Tags public_api -// @Description Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, justica-eleitoral, justica-superior e conselhos-de-justica. -// @Produce json -// @Success 200 {object} []aggregateIndexes "Requisição bem sucedida." -// @Failure 400 {string} string "Requisição inválida." -// @Failure 500 {string} string "Erro interno do servidor." -// @Param param path string true "'grupo' para pesquisar por jurisdição ou 'orgao' para pesquisar pela sigla do órgão" -// @Param valor path string true "Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, etc." -// @Param agregado query boolean false "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês." -// @Param detalhe query boolean false "Define se os metadados utilizados para calcular o índice serão retornados ou não." -// @Router /v2/indice/{param}/{valor} [get] +// @ID GetAggregateIndexesWithParams +// @Tags public_api +// @Description Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, justica-eleitoral, justica-superior e conselhos-de-justica. +// @Produce json +// @Success 200 {object} []aggregateIndexes "Requisição bem sucedida." +// @Failure 400 {string} string "Requisição inválida." +// @Failure 500 {string} string "Erro interno do servidor." +// @Param param path string true "'grupo' para pesquisar por jurisdição ou 'orgao' para pesquisar pela sigla do órgão" +// @Param valor path string true "Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, etc." +// @Param agregado query boolean false "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês." +// @Param detalhe query boolean false "Define se os metadados utilizados para calcular o índice serão retornados ou não." +// @Router /v2/indice/{param}/{valor} [get] func (h handler) V2GetAggregateIndexesWithParams(c echo.Context) error { param := c.Param("param") valor := c.Param("valor") @@ -690,50 +690,50 @@ func (h handler) V2GetAggregateIndexesWithParams(c echo.Context) error { return c.JSON(http.StatusOK, aggregate) } -// @ID GetAggregateIndexesWithParamsByYear -// @Tags public_api -// @Description Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, justica-eleitoral, justica-superior e conselhos-de-justica. -// @Produce json -// @Success 200 {object} []aggregateIndexes "Requisição bem sucedida." -// @Failure 400 {string} string "Requisição inválida." -// @Failure 500 {string} string "Erro interno do servidor." -// @Param param path string true "'grupo' para pesquisar por jurisdição ou 'orgao' para pesquisar pela sigla do órgão" -// @Param valor path string true "Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, etc." -// @Param ano path int true "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018)." -// @Param agregado query boolean false "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês." -// @Param detalhe query boolean false "Define se os metadados utilizados para calcular o índice serão retornados ou não." -// @Router /v2/indice/{param}/{valor}/{ano} [get] +// @ID GetAggregateIndexesWithParamsByYear +// @Tags public_api +// @Description Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, justica-eleitoral, justica-superior e conselhos-de-justica. +// @Produce json +// @Success 200 {object} []aggregateIndexes "Requisição bem sucedida." +// @Failure 400 {string} string "Requisição inválida." +// @Failure 500 {string} string "Erro interno do servidor." +// @Param param path string true "'grupo' para pesquisar por jurisdição ou 'orgao' para pesquisar pela sigla do órgão" +// @Param valor path string true "Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, etc." +// @Param ano path int true "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018)." +// @Param agregado query boolean false "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês." +// @Param detalhe query boolean false "Define se os metadados utilizados para calcular o índice serão retornados ou não." +// @Router /v2/indice/{param}/{valor}/{ano} [get] func (h handler) V2GetAggregateIndexesWithParamsByYear(c echo.Context) error { return h.V2GetAggregateIndexesWithParams(c) } -// @ID GetAggregateIndexesWithParamsByYearAndMonth -// @Tags public_api -// @Description Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, justica-eleitoral, justica-superior e conselhos-de-justica. -// @Produce json -// @Success 200 {object} []aggregateIndexes "Requisição bem sucedida." -// @Failure 400 {string} string "Requisição inválida." -// @Failure 500 {string} string "Erro interno do servidor." -// @Param param path string true "'grupo' para pesquisar por jurisdição ou 'orgao' para pesquisar pela sigla do órgão" -// @Param valor path string true "Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, etc." -// @Param ano path int true "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018)." -// @Param mes path int true "Mês para o qual os dados estão sendo solicitados (1-12)." -// @Param agregado query boolean false "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês." -// @Param detalhe query boolean false "Define se os metadados utilizados para calcular o índice serão retornados ou não." -// @Router /v2/indice/{param}/{valor}/{ano}/{mes} [get] +// @ID GetAggregateIndexesWithParamsByYearAndMonth +// @Tags public_api +// @Description Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) do órgão (param=orgao) ou da jurisdição (param=grupo) informada, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses). As jurisdições possíveis são: justica-estadual, ministerios-publicos, justica-do-trabalho, justica-militar, justica-federal, justica-eleitoral, justica-superior e conselhos-de-justica. +// @Produce json +// @Success 200 {object} []aggregateIndexes "Requisição bem sucedida." +// @Failure 400 {string} string "Requisição inválida." +// @Failure 500 {string} string "Erro interno do servidor." +// @Param param path string true "'grupo' para pesquisar por jurisdição ou 'orgao' para pesquisar pela sigla do órgão" +// @Param valor path string true "Jurisdição ou sigla do órgao. Ex.: tjal, mpdft, justica-estadual, etc." +// @Param ano path int true "Ano para o qual os dados estão sendo solicitados (dados disponíveis a partir de 2018)." +// @Param mes path int true "Mês para o qual os dados estão sendo solicitados (1-12)." +// @Param agregado query boolean false "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês." +// @Param detalhe query boolean false "Define se os metadados utilizados para calcular o índice serão retornados ou não." +// @Router /v2/indice/{param}/{valor}/{ano}/{mes} [get] func (h handler) V2GetAggregateIndexesWithParamsByYearAndMonth(c echo.Context) error { return h.V2GetAggregateIndexesWithParams(c) } -// @ID GetAggregateIndexes -// @Tags public_api -// @Description Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) de todos os órgãos, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses) organizando-os por jurisdição: Justiça Estadual, Ministérios Públicos, Justiça do Trabalho, Justiça Militar, Justiça Federal, Justiça Eleitoral, Justiça Superior e Conselhos de Justiça. -// @Produce json -// @Param agregado query boolean false "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês." -// @Param detalhe query boolean false "Define se os metadados utilizados para calcular o índice serão retornados ou não." -// @Success 200 {object} []aggregateIndexesByGroup "Requisição bem sucedida." -// @Failure 500 {string} string "Erro interno do servidor." -// @Router /v2/indice [get] +// @ID GetAggregateIndexes +// @Tags public_api +// @Description Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) de todos os órgãos, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses) organizando-os por jurisdição: Justiça Estadual, Ministérios Públicos, Justiça do Trabalho, Justiça Militar, Justiça Federal, Justiça Eleitoral, Justiça Superior e Conselhos de Justiça. +// @Produce json +// @Param agregado query boolean false "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês." +// @Param detalhe query boolean false "Define se os metadados utilizados para calcular o índice serão retornados ou não." +// @Success 200 {object} []aggregateIndexesByGroup "Requisição bem sucedida." +// @Failure 500 {string} string "Erro interno do servidor." +// @Router /v2/indice [get] func (h handler) V2GetAggregateIndexes(c echo.Context) error { agregado := c.QueryParam("agregado") detalhe := c.QueryParam("detalhe") @@ -837,14 +837,14 @@ func (h handler) V2GetAggregateIndexes(c echo.Context) error { return c.JSON(http.StatusOK, dados) } -// @ID GetAllAgencyInformation -// @Tags public_api -// @Description Busca todos os dados de um órgão específico trazendo informações de cada mês disponível para cada ano disponível a partir de 2018, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice). -// @Produce json -// @Success 200 {object} allAgencyInformation "Requisição bem sucedida." -// @Failure 400 {string} string "Requisição inválida." -// @Param orgao path string true "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb" -// @Router /v2/dados/{orgao} [get] +// @ID GetAllAgencyInformation +// @Tags public_api +// @Description Busca todos os dados de um órgão específico trazendo informações de cada mês disponível para cada ano disponível a partir de 2018, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice). +// @Produce json +// @Success 200 {object} allAgencyInformation "Requisição bem sucedida." +// @Failure 400 {string} string "Requisição inválida." +// @Param orgao path string true "Sigla do órgão para o qual os dados estão sendo solicitados. Ex.: tjal, tjba, mppb" +// @Router /v2/dados/{orgao} [get] func (h handler) V2GetAllAgencyInformation(c echo.Context) error { agency := strings.ToLower(c.Param("orgao")) From 258a9440f9bc1db0511fe32a3b67a99f8d85fc1f Mon Sep 17 00:00:00 2001 From: JezzDiego Date: Fri, 11 Apr 2025 11:18:00 -0300 Subject: [PATCH 4/7] docs: apply comments sugestions --- docs/docs.go | 8 ++++---- docs/swagger.json | 8 ++++---- docs/swagger.yaml | 40 ++++++++++++++++++++++------------------ papi/handlers.go | 10 +++++----- 4 files changed, 35 insertions(+), 31 deletions(-) diff --git a/docs/docs.go b/docs/docs.go index 0076da96..bd9bba8c 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -541,7 +541,7 @@ const docTemplate = `{ }, "/v2/dados/{orgao}": { "get": { - "description": "Busca todos os dados de um órgão específico trazendo informações de cada mês disponível para cada ano disponível a partir de 2018, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice).", + "description": "Busca todos os dados de um órgão específico trazendo informações de cada mês disponível para cada ano disponível a partir de 2018, retornando status de coleta, dados de coleta (duração da coleta e dados do coletor), dados sumarizados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuações referentes ao índice de transparência nas dimensões de completude, facilidade de acesso e transparência (https://dadosjusbr.org/indice).", "produces": [ "application/json" ], @@ -576,7 +576,7 @@ const docTemplate = `{ }, "/v2/dados/{orgao}/{ano}": { "get": { - "description": "Busca os dados mensais de um órgão específico trazendo informações de cada mês disponível para o ano informado, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice).", + "description": "Busca os dados mensais de um órgão específico trazendo informações de cada mês disponível para o ano informado, retornando status de coleta, dados de coleta (duração da coleta e dados do coletor), dados sumarizados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuações referentes ao índice de transparência nas dimensões de completude, facilidade de acesso e transparência (https://dadosjusbr.org/indice).", "produces": [ "application/json" ], @@ -627,7 +627,7 @@ const docTemplate = `{ }, "/v2/dados/{orgao}/{ano}/{mes}": { "get": { - "description": "Busca informações mensais de um órgão específico, incluindo dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice).", + "description": "Busca informações mensais de um órgão específico, incluindo dados de coleta (status e duração da coleta e dados do coletor), dados de remuneração sumarizados (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuações referentes ao índice de transparência nas dimensões de completude, facilidade de acesso e transparência (https://dadosjusbr.org/indice).", "produces": [ "application/json" ], @@ -682,7 +682,7 @@ const docTemplate = `{ }, "/v2/indice": { "get": { - "description": "Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) de todos os órgãos, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses) organizando-os por jurisdição: Justiça Estadual, Ministérios Públicos, Justiça do Trabalho, Justiça Militar, Justiça Federal, Justiça Eleitoral, Justiça Superior e Conselhos de Justiça.", + "description": "Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) de todos os órgãos, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do Índice de Transparência) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses) organizando-os por jurisdição: Justiça Estadual, Ministérios Públicos, Justiça do Trabalho, Justiça Militar, Justiça Federal, Justiça Eleitoral, Justiça Superior e Conselhos de Justiça.", "produces": [ "application/json" ], diff --git a/docs/swagger.json b/docs/swagger.json index 9870f399..069fda0e 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -532,7 +532,7 @@ }, "/v2/dados/{orgao}": { "get": { - "description": "Busca todos os dados de um órgão específico trazendo informações de cada mês disponível para cada ano disponível a partir de 2018, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice).", + "description": "Busca todos os dados de um órgão específico trazendo informações de cada mês disponível para cada ano disponível a partir de 2018, retornando status de coleta, dados de coleta (duração da coleta e dados do coletor), dados sumarizados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuações referentes ao índice de transparência nas dimensões de completude, facilidade de acesso e transparência (https://dadosjusbr.org/indice).", "produces": [ "application/json" ], @@ -567,7 +567,7 @@ }, "/v2/dados/{orgao}/{ano}": { "get": { - "description": "Busca os dados mensais de um órgão específico trazendo informações de cada mês disponível para o ano informado, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice).", + "description": "Busca os dados mensais de um órgão específico trazendo informações de cada mês disponível para o ano informado, retornando status de coleta, dados de coleta (duração da coleta e dados do coletor), dados sumarizados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuações referentes ao índice de transparência nas dimensões de completude, facilidade de acesso e transparência (https://dadosjusbr.org/indice).", "produces": [ "application/json" ], @@ -618,7 +618,7 @@ }, "/v2/dados/{orgao}/{ano}/{mes}": { "get": { - "description": "Busca informações mensais de um órgão específico, incluindo dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice).", + "description": "Busca informações mensais de um órgão específico, incluindo dados de coleta (status e duração da coleta e dados do coletor), dados de remuneração sumarizados (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuações referentes ao índice de transparência nas dimensões de completude, facilidade de acesso e transparência (https://dadosjusbr.org/indice).", "produces": [ "application/json" ], @@ -673,7 +673,7 @@ }, "/v2/indice": { "get": { - "description": "Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) de todos os órgãos, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses) organizando-os por jurisdição: Justiça Estadual, Ministérios Públicos, Justiça do Trabalho, Justiça Militar, Justiça Federal, Justiça Eleitoral, Justiça Superior e Conselhos de Justiça.", + "description": "Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) de todos os órgãos, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do Índice de Transparência) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses) organizando-os por jurisdição: Justiça Estadual, Ministérios Públicos, Justiça do Trabalho, Justiça Militar, Justiça Federal, Justiça Eleitoral, Justiça Superior e Conselhos de Justiça.", "produces": [ "application/json" ], diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 1f136497..239d8d93 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -1012,11 +1012,12 @@ paths: get: description: Busca todos os dados de um órgão específico trazendo informações de cada mês disponível para cada ano disponível a partir de 2018, retornando - dados de coleta (duração da coleta e dados do coletor), dados de remuneração - (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, - descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas - identificadas/penduricalhos), metadados de completude e facilidade de acesso - e pontuação de transparência (https://dadosjusbr.org/indice). + status de coleta, dados de coleta (duração da coleta e dados do coletor), + dados sumarizados de remuneração (dos membros ativos, remuneração base/salário, + outras remunerações/benefícios, descontos, remunerações líquidas, quantidade + de membros, e gasto em rubricas identificadas/penduricalhos), metadados de + completude e facilidade de acesso e pontuações referentes ao índice de transparência + nas dimensões de completude, facilidade de acesso e transparência (https://dadosjusbr.org/indice). operationId: GetAllAgencyInformation parameters: - description: 'Sigla do órgão para o qual os dados estão sendo solicitados. @@ -1041,11 +1042,13 @@ paths: /v2/dados/{orgao}/{ano}: get: description: Busca os dados mensais de um órgão específico trazendo informações - de cada mês disponível para o ano informado, retornando dados de coleta (duração - da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração - base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, - quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados - de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice). + de cada mês disponível para o ano informado, retornando status de coleta, + dados de coleta (duração da coleta e dados do coletor), dados sumarizados + de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, + descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas + identificadas/penduricalhos), metadados de completude e facilidade de acesso + e pontuações referentes ao índice de transparência nas dimensões de completude, + facilidade de acesso e transparência (https://dadosjusbr.org/indice). operationId: GetMonthlyInfosByYear parameters: - description: Ano para o qual os dados estão sendo solicitados (dados disponíveis @@ -1082,11 +1085,12 @@ paths: /v2/dados/{orgao}/{ano}/{mes}: get: description: Busca informações mensais de um órgão específico, incluindo dados - de coleta (duração da coleta e dados do coletor), dados de remuneração (dos - membros ativos, remuneração base/salário, outras remunerações/benefícios, + de coleta (status e duração da coleta e dados do coletor), dados de remuneração + sumarizados (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso - e pontuação de transparência (https://dadosjusbr.org/indice). + e pontuações referentes ao índice de transparência nas dimensões de completude, + facilidade de acesso e transparência (https://dadosjusbr.org/indice). operationId: GetMonthlyInfo parameters: - description: Ano para o qual os dados estão sendo solicitados (dados disponíveis @@ -1127,11 +1131,11 @@ paths: get: description: 'Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) de todos os órgãos, trazendo o detalhamento (granularidade mensal), os metadados - (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado - do Índice de Trasparência médio do órgão ao longo dos meses) organizando-os - por jurisdição: Justiça Estadual, Ministérios Públicos, Justiça do Trabalho, - Justiça Militar, Justiça Federal, Justiça Eleitoral, Justiça Superior e Conselhos - de Justiça.' + (critérios de avaliação do Índice de Transparência) e o objeto agregado do + detalhamento (compilado do Índice de Trasparência médio do órgão ao longo + dos meses) organizando-os por jurisdição: Justiça Estadual, Ministérios Públicos, + Justiça do Trabalho, Justiça Militar, Justiça Federal, Justiça Eleitoral, + Justiça Superior e Conselhos de Justiça.' operationId: GetAggregateIndexes parameters: - description: Alterna entre o Índice de Transparência geral de todos os órgãos diff --git a/papi/handlers.go b/papi/handlers.go index 6e8763e7..7c1d6cff 100644 --- a/papi/handlers.go +++ b/papi/handlers.go @@ -266,7 +266,7 @@ func (h handler) GetMonthlyInfo(c echo.Context) error { // @ID GetMonthlyInfo // @Tags public_api -// @Description Busca informações mensais de um órgão específico, incluindo dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice). +// @Description Busca informações mensais de um órgão específico, incluindo dados de coleta (status e duração da coleta e dados do coletor), dados de remuneração sumarizados (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuações referentes ao índice de transparência nas dimensões de completude, facilidade de acesso e transparência (https://dadosjusbr.org/indice). // @Produce json // @Success 200 {object} summaryzedMI "Requisição bem-sucedida com dados mensais" // @Failure 400 {string} string "Parâmetros inválidos" @@ -399,7 +399,7 @@ func (h handler) V2GetMonthlyInfo(c echo.Context) error { // @ID GetMonthlyInfosByYear // @Tags public_api -// @Description Busca os dados mensais de um órgão específico trazendo informações de cada mês disponível para o ano informado, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice). +// @Description Busca os dados mensais de um órgão específico trazendo informações de cada mês disponível para o ano informado, retornando status de coleta, dados de coleta (duração da coleta e dados do coletor), dados sumarizados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuações referentes ao índice de transparência nas dimensões de completude, facilidade de acesso e transparência (https://dadosjusbr.org/indice). // @Produce json // @Success 200 {object} []summaryzedMI "Requisição bem-sucedida com dados mensais" // @Failure 400 {string} string "Parâmetros inválidos" @@ -727,13 +727,13 @@ func (h handler) V2GetAggregateIndexesWithParamsByYearAndMonth(c echo.Context) e // @ID GetAggregateIndexes // @Tags public_api -// @Description Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) de todos os órgãos, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do índice) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses) organizando-os por jurisdição: Justiça Estadual, Ministérios Públicos, Justiça do Trabalho, Justiça Militar, Justiça Federal, Justiça Eleitoral, Justiça Superior e Conselhos de Justiça. +// @Description Busca informações do Índice de Transparência (https://dadosjusbr.org/indice) de todos os órgãos, trazendo o detalhamento (granularidade mensal), os metadados (critérios de avaliação do Índice de Transparência) e o objeto agregado do detalhamento (compilado do Índice de Trasparência médio do órgão ao longo dos meses) organizando-os por jurisdição: Justiça Estadual, Ministérios Públicos, Justiça do Trabalho, Justiça Militar, Justiça Federal, Justiça Eleitoral, Justiça Superior e Conselhos de Justiça. // @Produce json // @Param agregado query boolean false "Alterna entre o Índice de Transparência geral de todos os órgãos (true) ou o detalhamento do índice de cada órgão mês a mês." // @Param detalhe query boolean false "Define se os metadados utilizados para calcular o índice serão retornados ou não." // @Success 200 {object} []aggregateIndexesByGroup "Requisição bem sucedida." // @Failure 500 {string} string "Erro interno do servidor." -// @Router /v2/indice [get] +// @Router /v2/indice [get] func (h handler) V2GetAggregateIndexes(c echo.Context) error { agregado := c.QueryParam("agregado") detalhe := c.QueryParam("detalhe") @@ -839,7 +839,7 @@ func (h handler) V2GetAggregateIndexes(c echo.Context) error { // @ID GetAllAgencyInformation // @Tags public_api -// @Description Busca todos os dados de um órgão específico trazendo informações de cada mês disponível para cada ano disponível a partir de 2018, retornando dados de coleta (duração da coleta e dados do coletor), dados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuação de transparência (https://dadosjusbr.org/indice). +// @Description Busca todos os dados de um órgão específico trazendo informações de cada mês disponível para cada ano disponível a partir de 2018, retornando status de coleta, dados de coleta (duração da coleta e dados do coletor), dados sumarizados de remuneração (dos membros ativos, remuneração base/salário, outras remunerações/benefícios, descontos, remunerações líquidas, quantidade de membros, e gasto em rubricas identificadas/penduricalhos), metadados de completude e facilidade de acesso e pontuações referentes ao índice de transparência nas dimensões de completude, facilidade de acesso e transparência (https://dadosjusbr.org/indice). // @Produce json // @Success 200 {object} allAgencyInformation "Requisição bem sucedida." // @Failure 400 {string} string "Requisição inválida." From 6b84b9fbe921c328880b3d01c6bcbfa63c0c9b03 Mon Sep 17 00:00:00 2001 From: JezzDiego Date: Sat, 12 Apr 2025 10:58:34 -0300 Subject: [PATCH 5/7] docs: improve ui_api docs --- docs/docs.go | 111 ++++++++++++++----------- docs/swagger.json | 111 ++++++++++++++----------- docs/swagger.yaml | 202 +++++++++++++++++++++++++++++++++++----------- papi/handlers.go | 2 +- uiapi/handlers.go | 167 ++++++++++++++++++++++++++++---------- 5 files changed, 410 insertions(+), 183 deletions(-) diff --git a/docs/docs.go b/docs/docs.go index bd9bba8c..45c3e1cb 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -20,7 +20,7 @@ const docTemplate = `{ "paths": { "/uiapi/v1/orgao/resumo/{orgao}": { "get": { - "description": "Retorna os dados anuais de um orgão", + "description": "Retorna os dados de remuneração de todos os anos disponíveis para um órgão específico, incluindo:\n- Remuneração base/salário, outras remunerações/benefícios, descontos e remuneração líquida (salário+benefícios-descontos). Dados brutos, agrupados por mês e per capita\n- Quantidade de meses com dados no determinado ano\n- Quantidade média de membros do órgão naquele ano\n- Resumo dos benefícios identificados (rubricas/penduricalhos) e seus respectivos valores no ano\n- Informações do pacote de dados, URL do pacote de dados para download, seu hash e tamanho do pacote de dados (em bytes)", "produces": [ "application/json" ], @@ -64,7 +64,7 @@ const docTemplate = `{ }, "/uiapi/v2/download": { "get": { - "description": "Baixa dados referentes a remunerações a partir de filtros", + "description": "Baixa um arquivo csv referentes a remunerações a partir de filtros. O arquivo tem um limite de 10 mil linhas. Para cada parâmetro, é possível passar múltiplos valores separados por vírgula. As colunas do arquivo csv são:\n\n- Nome do órgão\n- Mês de referência do contracheque\n- Ano de referência do contracheque\n- Matrícula do membro (identificador único do membro no órgão)\n- Nome do membro\n- Cargo que o membro exerce no órgão\n- Lotação (unidade na qual o membro do órgão desenvolve suas atividades)\n- Categoria do contracheque (base, outras remunerações ou descontos)\n- Detalhamento do contracheque (ex: subsídio, desconto, benefício, etc)\n- Valor do contracheque em reais, não corrigido pela inflação", "produces": [ "application/json" ], @@ -98,7 +98,7 @@ const docTemplate = `{ "descontos" ], "type": "string", - "description": "Categorias a serem pesquisadas", + "description": "Categorias a serem pesquisadas. Se nada for informado, todas as categorias serão baixadas", "name": "categorias", "in": "query" } @@ -127,7 +127,7 @@ const docTemplate = `{ }, "/uiapi/v2/geral/remuneracao/{ano}": { "get": { - "description": "Busca os dados, das remunerações de um ano inteiro, agrupados por mês.", + "description": "Busca os dados, das remunerações (remuneração base/salário, outras remunerações/benefícios, descontos) e benefícios identificados (rubricas/penduricalhos) de um ano inteiro, agrupados por mês.", "produces": [ "application/json" ], @@ -138,7 +138,7 @@ const docTemplate = `{ "parameters": [ { "type": "string", - "description": "Ano da remuneração. Exemplos: 2018, 2019, 2020...", + "description": "Ano da remuneração. Ex.: 2018, 2019, 2020...", "name": "ano", "in": "path", "required": true @@ -171,7 +171,7 @@ const docTemplate = `{ }, "/uiapi/v2/geral/resumo": { "get": { - "description": "Busca e resume os dados das remunerações de todos os anos", + "description": "Busca e resume os dados das remunerações de todos os anos, trazendo o número de órgão participantes das tetativas de coleta (inclue os órgãos da coleta automatizada, coleta manual e órgãos não coletados, mas que armazenamos alguma informação), número total de meses coletados, data do primeiro e último mês coletado e o valor total de remuneração considerando todos os meses.", "produces": [ "application/json" ], @@ -197,7 +197,7 @@ const docTemplate = `{ }, "/uiapi/v2/orgao/resumo/{orgao}/{ano}/{mes}": { "get": { - "description": "Resume os dados de remuneração mensal de um órgão.", + "description": "Endpoint de resumo financeiro dos órgãos. Fornece uma análise financeira abrangente para um órgão específico em um mês e ano determinados\n\nInformações Financeiras Detalhadas:\n- Remuneração base total e máxima\n- Outras remunerações e benefícios\n- Valor total de descontos\n- Contagem de membros\n- Análise de rubricas (penduricalhos) específicas\n\nContexto Adicional:\n- Marcadores de existência de dados anteriores/posteriores ao ano/mês consultados\n- Timestamp da coleta de dados\n- Detalhamento de diferentes tipos de remuneração (remuneração base, outras remunerações e descontos)", "produces": [ "application/json" ], @@ -208,41 +208,47 @@ const docTemplate = `{ "parameters": [ { "type": "string", - "description": "ID do órgão. Exemplos: tjal, tjba, mppb.", + "description": "Sigla do órgão. Ex.: tjal, mppb, tjmmg", "name": "orgao", "in": "path", "required": true }, { - "type": "integer", - "description": "Ano da remuneração. Exemplo: 2018.", - "name": "ano", + "type": "string", + "description": "Mês de referência (1-12)", + "name": "mes", "in": "path", "required": true }, { - "type": "integer", - "description": "Mês da remuneração. Exemplo: 1.", - "name": "mes", + "type": "string", + "description": "Ano de referência", + "name": "ano", "in": "path", "required": true } ], "responses": { "200": { - "description": "Requisição bem sucedida.", + "description": "Resumo financeiro do órgão processado com sucesso", "schema": { "$ref": "#/definitions/uiapi.v2AgencySummary" } }, "400": { - "description": "Parâmetro ano, mês ou nome do órgão são inválidos.", + "description": "Erro de validação dos parâmetros de entrada", "schema": { "type": "string" } }, "404": { - "description": "Órgão não encontrado.", + "description": "Órgão ou dados não encontrados", + "schema": { + "type": "string" + } + }, + "500": { + "description": "Erro interno durante processamento da consulta", "schema": { "type": "string" } @@ -252,7 +258,7 @@ const docTemplate = `{ }, "/uiapi/v2/orgao/salario/{orgao}/{ano}/{mes}": { "get": { - "description": "Busca dados das remunerações mensais de um órgão.", + "description": "Endpoint de análise detalhada de remunerações dos órgãos. Recupera informações financeiras granulares para um órgão específico em um mês e ano determinados\n\nInformações Fornecidos:\n- Remuneração máxima no período\n- Histograma de distribuição de rendimentos\n- Metadados do pacote de dados\n\nHistograma de Distribuição de Rendimentos:\n\nO histograma apresenta a quantidade de membros que receberam diferentes faixas de remunerações em um determinado mês.\nAs faixas de remuneração são definidas da seguinte forma:\n- 10000: quantidade de membros que receberam até R$ 10.000,00\n- 20000: quantidade de membros que receberam entre R$ 10.000,01 e R$ 20.000,00\n- 30000: quantidade de membros que receberam entre R$ 20.000,01 e R$ 30.000,00\n- 40000: quantidade de membros que receberam entre R$ 30.000,01 e R$ 40.000,00\n- 50000: quantidade de membros que receberam entre R$ 40.000,01 e R$ 50.000,00\n- -1: quantidade de membros que receberam acima de R$ 50.000,01", "produces": [ "application/json" ], @@ -263,21 +269,21 @@ const docTemplate = `{ "parameters": [ { "type": "string", - "description": "ID do órgão. Exemplos: tjal, tjba, mppb.", + "description": "Sigla do órgão. Ex.: tjal, mppb, tjmmg", "name": "orgao", "in": "path", "required": true }, { "type": "string", - "description": "Mês da remuneração. Exemplos: 01, 02, 03...", + "description": "Mês de referência (1-12)", "name": "mes", "in": "path", "required": true }, { "type": "string", - "description": "Ano da remuneração. Exemplos: 2018, 2019, 2020...", + "description": "Ano de referência", "name": "ano", "in": "path", "required": true @@ -285,19 +291,25 @@ const docTemplate = `{ ], "responses": { "200": { - "description": "Requisição bem sucedida.", + "description": "Dados de remuneração processados com sucesso", "schema": { "$ref": "#/definitions/uiapi.agencyRemuneration" } }, "206": { - "description": "Requisição bem sucedida, mas os dados do órgão não foram bem processados", + "description": "Dados coletados com informações de processamento", "schema": { "$ref": "#/definitions/uiapi.v2ProcInfoResult" } }, "400": { - "description": "Parâmetros inválidos.", + "description": "Erro de validação dos parâmetros de entrada", + "schema": { + "type": "string" + } + }, + "500": { + "description": "Erro interno durante processamento da consulta", "schema": { "type": "string" } @@ -307,7 +319,7 @@ const docTemplate = `{ }, "/uiapi/v2/orgao/totais/{orgao}/{ano}": { "get": { - "description": "Busca os dados de remuneração de um órgão em um ano específico.", + "description": "Recupera dados financeiros detalhados para um órgão em um ano específico\n\nDados Financeiros Mensais:\n- Remuneração base\n- Outras remunerações e benefícios\n- Descontos\n- Contagem de membros\n\nMétricas Adicionais:\n- Médias per capita\n- Detalhamento de rubricas (auxílios, férias, gratificações)\n- Informações gerais sobre o órgão pesquisado\n- Informações sobre o pacote de dados (URL para download, hash, tamanho)", "produces": [ "application/json" ], @@ -318,14 +330,14 @@ const docTemplate = `{ "parameters": [ { "type": "string", - "description": "ID do órgão. Exemplos: tjal, tjba, mppb.", + "description": "Identificador do órgão público", "name": "orgao", "in": "path", "required": true }, { "type": "integer", - "description": "Ano. Exemplo: 2018.", + "description": "Ano de referência para a consulta", "name": "ano", "in": "path", "required": true @@ -333,13 +345,19 @@ const docTemplate = `{ ], "responses": { "200": { - "description": "Requisição bem sucedida.", + "description": "Dados financeiros completos do órgão no ano especificado", "schema": { "$ref": "#/definitions/uiapi.v2AgencyTotalsYear" } }, "400": { - "description": "Parâmetro ano ou orgao inválido.", + "description": "Erro de validação: parâmetros de órgão ou ano inválidos", + "schema": { + "type": "string" + } + }, + "500": { + "description": "Erro interno durante processamento da consulta", "schema": { "type": "string" } @@ -426,7 +444,7 @@ const docTemplate = `{ }, "/uiapi/v2/pesquisar": { "get": { - "description": "Faz uma busca por remunerações a partir de filtros", + "description": "Endpoint de busca avançada para remunerações de servidores públicos\n\nPermite realizar pesquisas detalhadas nas remunerações de servidores públicos com múltiplos filtros flexíveis:\n\n- Filtragem por anos específicos\n- Seleção de meses específicos\n- Pesquisa por órgãos públicos de diferentes esferas\n- Categorias de remuneração\n\nCaracterísticas principais:\n- Suporta múltiplas seleções em cada filtro\n- Permite combinações complexas de busca\n- Retorna dados consolidados de remuneração dos contracheques por membros\n\nCasos de uso:\n- Análise comparativa de remunerações entre diferentes órgãos\n- Análise análise granular das remunerações por membros dos órgãos", "produces": [ "application/json" ], @@ -437,19 +455,19 @@ const docTemplate = `{ "parameters": [ { "type": "string", - "description": "Anos a serem pesquisados, separados por virgula. Exemplo: 2018,2019,2020", + "description": "Lista de anos a serem pesquisados, separados por virgula. Exemplo: 2018,2019,2020", "name": "anos", "in": "query" }, { "type": "string", - "description": "Meses a serem pesquisados, separados por virgula. Exemplo: 1,2,3", + "description": "Lista de meses a serem pesquisados, separados por virgula. Exemplo: 1,2,3", "name": "meses", "in": "query" }, { "type": "string", - "description": "Orgãos a serem pesquisados, separados por virgula. Exemplo: tjal,mpal,mppb", + "description": "Lista de órgãos a serem pesquisados, separados por virgula. Exemplo: tjal,mpal,mppb", "name": "orgaos", "in": "query" }, @@ -460,26 +478,26 @@ const docTemplate = `{ "descontos" ], "type": "string", - "description": "Categorias a serem pesquisadas", + "description": "Categorias a serem pesquisadas. Remuneração base (salário), outras remunerações (benefícios) e descontos", "name": "categorias", "in": "query" } ], "responses": { "200": { - "description": "Requisição bem sucedida.", + "description": "Requisição bem-sucedida com dados de remuneração", "schema": { "$ref": "#/definitions/uiapi.searchResponse" } }, "400": { - "description": "Erro de validação dos parâmetros.", + "description": "Erro de validação dos parâmetros de busca", "schema": { "type": "string" } }, "500": { - "description": "Erro interno do servidor.", + "description": "Erro interno do servidor durante processamento da pesquisa", "schema": { "type": "string" } @@ -489,9 +507,9 @@ const docTemplate = `{ }, "/uiapi/v2/readme": { "get": { - "description": "Retorna um README sobre o pacote de dados", + "description": "Recupera o arquivo README com informações sobre o conjunto de dados. Permite filtrar o README com base em parâmetros opcionais de ano, mês e órgão\n\nComportamentos:\n- Se nenhum filtro for aplicado, retorna o README original\n- Com filtro de órgão, gera um README com observações específicas sobre potenciais falhas nos dados", "produces": [ - "application/json" + "text/plain" ], "tags": [ "ui_api" @@ -500,38 +518,41 @@ const docTemplate = `{ "parameters": [ { "type": "string", - "description": "Ano a ser filtrado", + "default": "2024", + "description": "Ano para filtragem dos dados", "name": "ano", "in": "query" }, { "type": "string", - "description": "Mês a ser filtrado", + "default": "12", + "description": "Mês para filtragem dos dados", "name": "mes", "in": "query" }, { "type": "string", - "description": "Orgão a ser filtrado", + "default": "tjrr", + "description": "Sigla do órgão para filtragem. Ex.: tjal, mppb, mpdft", "name": "orgao", "in": "query" } ], "responses": { "200": { - "description": "OK", + "description": "README.txt com conteúdo detalhado", "schema": { "type": "string" } }, "400": { - "description": "Parâmetro ano/mês inválido", + "description": "Erro de validação de parâmetros (ano/mês inválidos)", "schema": { "type": "string" } }, "500": { - "description": "Algo deu errado ao retornar o README", + "description": "Erro interno ao processar o README", "schema": { "type": "string" } diff --git a/docs/swagger.json b/docs/swagger.json index 069fda0e..704351c2 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -11,7 +11,7 @@ "paths": { "/uiapi/v1/orgao/resumo/{orgao}": { "get": { - "description": "Retorna os dados anuais de um orgão", + "description": "Retorna os dados de remuneração de todos os anos disponíveis para um órgão específico, incluindo:\n- Remuneração base/salário, outras remunerações/benefícios, descontos e remuneração líquida (salário+benefícios-descontos). Dados brutos, agrupados por mês e per capita\n- Quantidade de meses com dados no determinado ano\n- Quantidade média de membros do órgão naquele ano\n- Resumo dos benefícios identificados (rubricas/penduricalhos) e seus respectivos valores no ano\n- Informações do pacote de dados, URL do pacote de dados para download, seu hash e tamanho do pacote de dados (em bytes)", "produces": [ "application/json" ], @@ -55,7 +55,7 @@ }, "/uiapi/v2/download": { "get": { - "description": "Baixa dados referentes a remunerações a partir de filtros", + "description": "Baixa um arquivo csv referentes a remunerações a partir de filtros. O arquivo tem um limite de 10 mil linhas. Para cada parâmetro, é possível passar múltiplos valores separados por vírgula. As colunas do arquivo csv são:\n\n- Nome do órgão\n- Mês de referência do contracheque\n- Ano de referência do contracheque\n- Matrícula do membro (identificador único do membro no órgão)\n- Nome do membro\n- Cargo que o membro exerce no órgão\n- Lotação (unidade na qual o membro do órgão desenvolve suas atividades)\n- Categoria do contracheque (base, outras remunerações ou descontos)\n- Detalhamento do contracheque (ex: subsídio, desconto, benefício, etc)\n- Valor do contracheque em reais, não corrigido pela inflação", "produces": [ "application/json" ], @@ -89,7 +89,7 @@ "descontos" ], "type": "string", - "description": "Categorias a serem pesquisadas", + "description": "Categorias a serem pesquisadas. Se nada for informado, todas as categorias serão baixadas", "name": "categorias", "in": "query" } @@ -118,7 +118,7 @@ }, "/uiapi/v2/geral/remuneracao/{ano}": { "get": { - "description": "Busca os dados, das remunerações de um ano inteiro, agrupados por mês.", + "description": "Busca os dados, das remunerações (remuneração base/salário, outras remunerações/benefícios, descontos) e benefícios identificados (rubricas/penduricalhos) de um ano inteiro, agrupados por mês.", "produces": [ "application/json" ], @@ -129,7 +129,7 @@ "parameters": [ { "type": "string", - "description": "Ano da remuneração. Exemplos: 2018, 2019, 2020...", + "description": "Ano da remuneração. Ex.: 2018, 2019, 2020...", "name": "ano", "in": "path", "required": true @@ -162,7 +162,7 @@ }, "/uiapi/v2/geral/resumo": { "get": { - "description": "Busca e resume os dados das remunerações de todos os anos", + "description": "Busca e resume os dados das remunerações de todos os anos, trazendo o número de órgão participantes das tetativas de coleta (inclue os órgãos da coleta automatizada, coleta manual e órgãos não coletados, mas que armazenamos alguma informação), número total de meses coletados, data do primeiro e último mês coletado e o valor total de remuneração considerando todos os meses.", "produces": [ "application/json" ], @@ -188,7 +188,7 @@ }, "/uiapi/v2/orgao/resumo/{orgao}/{ano}/{mes}": { "get": { - "description": "Resume os dados de remuneração mensal de um órgão.", + "description": "Endpoint de resumo financeiro dos órgãos. Fornece uma análise financeira abrangente para um órgão específico em um mês e ano determinados\n\nInformações Financeiras Detalhadas:\n- Remuneração base total e máxima\n- Outras remunerações e benefícios\n- Valor total de descontos\n- Contagem de membros\n- Análise de rubricas (penduricalhos) específicas\n\nContexto Adicional:\n- Marcadores de existência de dados anteriores/posteriores ao ano/mês consultados\n- Timestamp da coleta de dados\n- Detalhamento de diferentes tipos de remuneração (remuneração base, outras remunerações e descontos)", "produces": [ "application/json" ], @@ -199,41 +199,47 @@ "parameters": [ { "type": "string", - "description": "ID do órgão. Exemplos: tjal, tjba, mppb.", + "description": "Sigla do órgão. Ex.: tjal, mppb, tjmmg", "name": "orgao", "in": "path", "required": true }, { - "type": "integer", - "description": "Ano da remuneração. Exemplo: 2018.", - "name": "ano", + "type": "string", + "description": "Mês de referência (1-12)", + "name": "mes", "in": "path", "required": true }, { - "type": "integer", - "description": "Mês da remuneração. Exemplo: 1.", - "name": "mes", + "type": "string", + "description": "Ano de referência", + "name": "ano", "in": "path", "required": true } ], "responses": { "200": { - "description": "Requisição bem sucedida.", + "description": "Resumo financeiro do órgão processado com sucesso", "schema": { "$ref": "#/definitions/uiapi.v2AgencySummary" } }, "400": { - "description": "Parâmetro ano, mês ou nome do órgão são inválidos.", + "description": "Erro de validação dos parâmetros de entrada", "schema": { "type": "string" } }, "404": { - "description": "Órgão não encontrado.", + "description": "Órgão ou dados não encontrados", + "schema": { + "type": "string" + } + }, + "500": { + "description": "Erro interno durante processamento da consulta", "schema": { "type": "string" } @@ -243,7 +249,7 @@ }, "/uiapi/v2/orgao/salario/{orgao}/{ano}/{mes}": { "get": { - "description": "Busca dados das remunerações mensais de um órgão.", + "description": "Endpoint de análise detalhada de remunerações dos órgãos. Recupera informações financeiras granulares para um órgão específico em um mês e ano determinados\n\nInformações Fornecidos:\n- Remuneração máxima no período\n- Histograma de distribuição de rendimentos\n- Metadados do pacote de dados\n\nHistograma de Distribuição de Rendimentos:\n\nO histograma apresenta a quantidade de membros que receberam diferentes faixas de remunerações em um determinado mês.\nAs faixas de remuneração são definidas da seguinte forma:\n- 10000: quantidade de membros que receberam até R$ 10.000,00\n- 20000: quantidade de membros que receberam entre R$ 10.000,01 e R$ 20.000,00\n- 30000: quantidade de membros que receberam entre R$ 20.000,01 e R$ 30.000,00\n- 40000: quantidade de membros que receberam entre R$ 30.000,01 e R$ 40.000,00\n- 50000: quantidade de membros que receberam entre R$ 40.000,01 e R$ 50.000,00\n- -1: quantidade de membros que receberam acima de R$ 50.000,01", "produces": [ "application/json" ], @@ -254,21 +260,21 @@ "parameters": [ { "type": "string", - "description": "ID do órgão. Exemplos: tjal, tjba, mppb.", + "description": "Sigla do órgão. Ex.: tjal, mppb, tjmmg", "name": "orgao", "in": "path", "required": true }, { "type": "string", - "description": "Mês da remuneração. Exemplos: 01, 02, 03...", + "description": "Mês de referência (1-12)", "name": "mes", "in": "path", "required": true }, { "type": "string", - "description": "Ano da remuneração. Exemplos: 2018, 2019, 2020...", + "description": "Ano de referência", "name": "ano", "in": "path", "required": true @@ -276,19 +282,25 @@ ], "responses": { "200": { - "description": "Requisição bem sucedida.", + "description": "Dados de remuneração processados com sucesso", "schema": { "$ref": "#/definitions/uiapi.agencyRemuneration" } }, "206": { - "description": "Requisição bem sucedida, mas os dados do órgão não foram bem processados", + "description": "Dados coletados com informações de processamento", "schema": { "$ref": "#/definitions/uiapi.v2ProcInfoResult" } }, "400": { - "description": "Parâmetros inválidos.", + "description": "Erro de validação dos parâmetros de entrada", + "schema": { + "type": "string" + } + }, + "500": { + "description": "Erro interno durante processamento da consulta", "schema": { "type": "string" } @@ -298,7 +310,7 @@ }, "/uiapi/v2/orgao/totais/{orgao}/{ano}": { "get": { - "description": "Busca os dados de remuneração de um órgão em um ano específico.", + "description": "Recupera dados financeiros detalhados para um órgão em um ano específico\n\nDados Financeiros Mensais:\n- Remuneração base\n- Outras remunerações e benefícios\n- Descontos\n- Contagem de membros\n\nMétricas Adicionais:\n- Médias per capita\n- Detalhamento de rubricas (auxílios, férias, gratificações)\n- Informações gerais sobre o órgão pesquisado\n- Informações sobre o pacote de dados (URL para download, hash, tamanho)", "produces": [ "application/json" ], @@ -309,14 +321,14 @@ "parameters": [ { "type": "string", - "description": "ID do órgão. Exemplos: tjal, tjba, mppb.", + "description": "Identificador do órgão público", "name": "orgao", "in": "path", "required": true }, { "type": "integer", - "description": "Ano. Exemplo: 2018.", + "description": "Ano de referência para a consulta", "name": "ano", "in": "path", "required": true @@ -324,13 +336,19 @@ ], "responses": { "200": { - "description": "Requisição bem sucedida.", + "description": "Dados financeiros completos do órgão no ano especificado", "schema": { "$ref": "#/definitions/uiapi.v2AgencyTotalsYear" } }, "400": { - "description": "Parâmetro ano ou orgao inválido.", + "description": "Erro de validação: parâmetros de órgão ou ano inválidos", + "schema": { + "type": "string" + } + }, + "500": { + "description": "Erro interno durante processamento da consulta", "schema": { "type": "string" } @@ -417,7 +435,7 @@ }, "/uiapi/v2/pesquisar": { "get": { - "description": "Faz uma busca por remunerações a partir de filtros", + "description": "Endpoint de busca avançada para remunerações de servidores públicos\n\nPermite realizar pesquisas detalhadas nas remunerações de servidores públicos com múltiplos filtros flexíveis:\n\n- Filtragem por anos específicos\n- Seleção de meses específicos\n- Pesquisa por órgãos públicos de diferentes esferas\n- Categorias de remuneração\n\nCaracterísticas principais:\n- Suporta múltiplas seleções em cada filtro\n- Permite combinações complexas de busca\n- Retorna dados consolidados de remuneração dos contracheques por membros\n\nCasos de uso:\n- Análise comparativa de remunerações entre diferentes órgãos\n- Análise análise granular das remunerações por membros dos órgãos", "produces": [ "application/json" ], @@ -428,19 +446,19 @@ "parameters": [ { "type": "string", - "description": "Anos a serem pesquisados, separados por virgula. Exemplo: 2018,2019,2020", + "description": "Lista de anos a serem pesquisados, separados por virgula. Exemplo: 2018,2019,2020", "name": "anos", "in": "query" }, { "type": "string", - "description": "Meses a serem pesquisados, separados por virgula. Exemplo: 1,2,3", + "description": "Lista de meses a serem pesquisados, separados por virgula. Exemplo: 1,2,3", "name": "meses", "in": "query" }, { "type": "string", - "description": "Orgãos a serem pesquisados, separados por virgula. Exemplo: tjal,mpal,mppb", + "description": "Lista de órgãos a serem pesquisados, separados por virgula. Exemplo: tjal,mpal,mppb", "name": "orgaos", "in": "query" }, @@ -451,26 +469,26 @@ "descontos" ], "type": "string", - "description": "Categorias a serem pesquisadas", + "description": "Categorias a serem pesquisadas. Remuneração base (salário), outras remunerações (benefícios) e descontos", "name": "categorias", "in": "query" } ], "responses": { "200": { - "description": "Requisição bem sucedida.", + "description": "Requisição bem-sucedida com dados de remuneração", "schema": { "$ref": "#/definitions/uiapi.searchResponse" } }, "400": { - "description": "Erro de validação dos parâmetros.", + "description": "Erro de validação dos parâmetros de busca", "schema": { "type": "string" } }, "500": { - "description": "Erro interno do servidor.", + "description": "Erro interno do servidor durante processamento da pesquisa", "schema": { "type": "string" } @@ -480,9 +498,9 @@ }, "/uiapi/v2/readme": { "get": { - "description": "Retorna um README sobre o pacote de dados", + "description": "Recupera o arquivo README com informações sobre o conjunto de dados. Permite filtrar o README com base em parâmetros opcionais de ano, mês e órgão\n\nComportamentos:\n- Se nenhum filtro for aplicado, retorna o README original\n- Com filtro de órgão, gera um README com observações específicas sobre potenciais falhas nos dados", "produces": [ - "application/json" + "text/plain" ], "tags": [ "ui_api" @@ -491,38 +509,41 @@ "parameters": [ { "type": "string", - "description": "Ano a ser filtrado", + "default": "2024", + "description": "Ano para filtragem dos dados", "name": "ano", "in": "query" }, { "type": "string", - "description": "Mês a ser filtrado", + "default": "12", + "description": "Mês para filtragem dos dados", "name": "mes", "in": "query" }, { "type": "string", - "description": "Orgão a ser filtrado", + "default": "tjrr", + "description": "Sigla do órgão para filtragem. Ex.: tjal, mppb, mpdft", "name": "orgao", "in": "query" } ], "responses": { "200": { - "description": "OK", + "description": "README.txt com conteúdo detalhado", "schema": { "type": "string" } }, "400": { - "description": "Parâmetro ano/mês inválido", + "description": "Erro de validação de parâmetros (ano/mês inválidos)", "schema": { "type": "string" } }, "500": { - "description": "Algo deu errado ao retornar o README", + "description": "Erro interno ao processar o README", "schema": { "type": "string" } diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 239d8d93..c5124ebf 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -649,7 +649,13 @@ info: paths: /uiapi/v1/orgao/resumo/{orgao}: get: - description: Retorna os dados anuais de um orgão + description: |- + Retorna os dados de remuneração de todos os anos disponíveis para um órgão específico, incluindo: + - Remuneração base/salário, outras remunerações/benefícios, descontos e remuneração líquida (salário+benefícios-descontos). Dados brutos, agrupados por mês e per capita + - Quantidade de meses com dados no determinado ano + - Quantidade média de membros do órgão naquele ano + - Resumo dos benefícios identificados (rubricas/penduricalhos) e seus respectivos valores no ano + - Informações do pacote de dados, URL do pacote de dados para download, seu hash e tamanho do pacote de dados (em bytes) operationId: GetAnnualSummary parameters: - description: Nome do orgão @@ -678,7 +684,19 @@ paths: - ui_api /uiapi/v2/download: get: - description: Baixa dados referentes a remunerações a partir de filtros + description: |- + Baixa um arquivo csv referentes a remunerações a partir de filtros. O arquivo tem um limite de 10 mil linhas. Para cada parâmetro, é possível passar múltiplos valores separados por vírgula. As colunas do arquivo csv são: + + - Nome do órgão + - Mês de referência do contracheque + - Ano de referência do contracheque + - Matrícula do membro (identificador único do membro no órgão) + - Nome do membro + - Cargo que o membro exerce no órgão + - Lotação (unidade na qual o membro do órgão desenvolve suas atividades) + - Categoria do contracheque (base, outras remunerações ou descontos) + - Detalhamento do contracheque (ex: subsídio, desconto, benefício, etc) + - Valor do contracheque em reais, não corrigido pela inflação operationId: DownloadByUrl parameters: - description: 'Anos a serem pesquisados, separados por virgula. Exemplo: 2018,2019,2020' @@ -694,7 +712,8 @@ paths: in: query name: orgaos type: string - - description: Categorias a serem pesquisadas + - description: Categorias a serem pesquisadas. Se nada for informado, todas + as categorias serão baixadas enum: - base - outras @@ -721,11 +740,12 @@ paths: - ui_api /uiapi/v2/geral/remuneracao/{ano}: get: - description: Busca os dados, das remunerações de um ano inteiro, agrupados por - mês. + description: Busca os dados, das remunerações (remuneração base/salário, outras + remunerações/benefícios, descontos) e benefícios identificados (rubricas/penduricalhos) + de um ano inteiro, agrupados por mês. operationId: GetGeneralRemunerationFromYear parameters: - - description: 'Ano da remuneração. Exemplos: 2018, 2019, 2020...' + - description: 'Ano da remuneração. Ex.: 2018, 2019, 2020...' in: path name: ano required: true @@ -751,7 +771,11 @@ paths: - ui_api /uiapi/v2/geral/resumo: get: - description: Busca e resume os dados das remunerações de todos os anos + description: Busca e resume os dados das remunerações de todos os anos, trazendo + o número de órgão participantes das tetativas de coleta (inclue os órgãos + da coleta automatizada, coleta manual e órgãos não coletados, mas que armazenamos + alguma informação), número total de meses coletados, data do primeiro e último + mês coletado e o valor total de remuneração considerando todos os meses. operationId: GetGeneralSummary produces: - application/json @@ -830,57 +854,91 @@ paths: - ui_api /uiapi/v2/orgao/resumo/{orgao}/{ano}/{mes}: get: - description: Resume os dados de remuneração mensal de um órgão. + description: |- + Endpoint de resumo financeiro dos órgãos. Fornece uma análise financeira abrangente para um órgão específico em um mês e ano determinados + + Informações Financeiras Detalhadas: + - Remuneração base total e máxima + - Outras remunerações e benefícios + - Valor total de descontos + - Contagem de membros + - Análise de rubricas (penduricalhos) específicas + + Contexto Adicional: + - Marcadores de existência de dados anteriores/posteriores ao ano/mês consultados + - Timestamp da coleta de dados + - Detalhamento de diferentes tipos de remuneração (remuneração base, outras remunerações e descontos) operationId: GetSummaryOfAgency parameters: - - description: 'ID do órgão. Exemplos: tjal, tjba, mppb.' + - description: 'Sigla do órgão. Ex.: tjal, mppb, tjmmg' in: path name: orgao required: true type: string - - description: 'Ano da remuneração. Exemplo: 2018.' + - description: Mês de referência (1-12) in: path - name: ano + name: mes required: true - type: integer - - description: 'Mês da remuneração. Exemplo: 1.' + type: string + - description: Ano de referência in: path - name: mes + name: ano required: true - type: integer + type: string produces: - application/json responses: "200": - description: Requisição bem sucedida. + description: Resumo financeiro do órgão processado com sucesso schema: $ref: '#/definitions/uiapi.v2AgencySummary' "400": - description: Parâmetro ano, mês ou nome do órgão são inválidos. + description: Erro de validação dos parâmetros de entrada schema: type: string "404": - description: Órgão não encontrado. + description: Órgão ou dados não encontrados + schema: + type: string + "500": + description: Erro interno durante processamento da consulta schema: type: string tags: - ui_api /uiapi/v2/orgao/salario/{orgao}/{ano}/{mes}: get: - description: Busca dados das remunerações mensais de um órgão. + description: |- + Endpoint de análise detalhada de remunerações dos órgãos. Recupera informações financeiras granulares para um órgão específico em um mês e ano determinados + + Informações Fornecidos: + - Remuneração máxima no período + - Histograma de distribuição de rendimentos + - Metadados do pacote de dados + + Histograma de Distribuição de Rendimentos: + + O histograma apresenta a quantidade de membros que receberam diferentes faixas de remunerações em um determinado mês. + As faixas de remuneração são definidas da seguinte forma: + - 10000: quantidade de membros que receberam até R$ 10.000,00 + - 20000: quantidade de membros que receberam entre R$ 10.000,01 e R$ 20.000,00 + - 30000: quantidade de membros que receberam entre R$ 20.000,01 e R$ 30.000,00 + - 40000: quantidade de membros que receberam entre R$ 30.000,01 e R$ 40.000,00 + - 50000: quantidade de membros que receberam entre R$ 40.000,01 e R$ 50.000,00 + - -1: quantidade de membros que receberam acima de R$ 50.000,01 operationId: GetSalaryOfAgencyMonthYear parameters: - - description: 'ID do órgão. Exemplos: tjal, tjba, mppb.' + - description: 'Sigla do órgão. Ex.: tjal, mppb, tjmmg' in: path name: orgao required: true type: string - - description: 'Mês da remuneração. Exemplos: 01, 02, 03...' + - description: Mês de referência (1-12) in: path name: mes required: true type: string - - description: 'Ano da remuneração. Exemplos: 2018, 2019, 2020...' + - description: Ano de referência in: path name: ano required: true @@ -889,31 +947,47 @@ paths: - application/json responses: "200": - description: Requisição bem sucedida. + description: Dados de remuneração processados com sucesso schema: $ref: '#/definitions/uiapi.agencyRemuneration' "206": - description: Requisição bem sucedida, mas os dados do órgão não foram bem - processados + description: Dados coletados com informações de processamento schema: $ref: '#/definitions/uiapi.v2ProcInfoResult' "400": - description: Parâmetros inválidos. + description: Erro de validação dos parâmetros de entrada + schema: + type: string + "500": + description: Erro interno durante processamento da consulta schema: type: string tags: - ui_api /uiapi/v2/orgao/totais/{orgao}/{ano}: get: - description: Busca os dados de remuneração de um órgão em um ano específico. + description: |- + Recupera dados financeiros detalhados para um órgão em um ano específico + + Dados Financeiros Mensais: + - Remuneração base + - Outras remunerações e benefícios + - Descontos + - Contagem de membros + + Métricas Adicionais: + - Médias per capita + - Detalhamento de rubricas (auxílios, férias, gratificações) + - Informações gerais sobre o órgão pesquisado + - Informações sobre o pacote de dados (URL para download, hash, tamanho) operationId: GetTotalsOfAgencyYear parameters: - - description: 'ID do órgão. Exemplos: tjal, tjba, mppb.' + - description: Identificador do órgão público in: path name: orgao required: true type: string - - description: 'Ano. Exemplo: 2018.' + - description: Ano de referência para a consulta in: path name: ano required: true @@ -922,34 +996,58 @@ paths: - application/json responses: "200": - description: Requisição bem sucedida. + description: Dados financeiros completos do órgão no ano especificado schema: $ref: '#/definitions/uiapi.v2AgencyTotalsYear' "400": - description: Parâmetro ano ou orgao inválido. + description: 'Erro de validação: parâmetros de órgão ou ano inválidos' + schema: + type: string + "500": + description: Erro interno durante processamento da consulta schema: type: string tags: - ui_api /uiapi/v2/pesquisar: get: - description: Faz uma busca por remunerações a partir de filtros + description: |- + Endpoint de busca avançada para remunerações de servidores públicos + + Permite realizar pesquisas detalhadas nas remunerações de servidores públicos com múltiplos filtros flexíveis: + + - Filtragem por anos específicos + - Seleção de meses específicos + - Pesquisa por órgãos públicos de diferentes esferas + - Categorias de remuneração + + Características principais: + - Suporta múltiplas seleções em cada filtro + - Permite combinações complexas de busca + - Retorna dados consolidados de remuneração dos contracheques por membros + + Casos de uso: + - Análise comparativa de remunerações entre diferentes órgãos + - Análise análise granular das remunerações por membros dos órgãos operationId: SearchByUrl parameters: - - description: 'Anos a serem pesquisados, separados por virgula. Exemplo: 2018,2019,2020' + - description: 'Lista de anos a serem pesquisados, separados por virgula. Exemplo: + 2018,2019,2020' in: query name: anos type: string - - description: 'Meses a serem pesquisados, separados por virgula. Exemplo: 1,2,3' + - description: 'Lista de meses a serem pesquisados, separados por virgula. Exemplo: + 1,2,3' in: query name: meses type: string - - description: 'Orgãos a serem pesquisados, separados por virgula. Exemplo: - tjal,mpal,mppb' + - description: 'Lista de órgãos a serem pesquisados, separados por virgula. + Exemplo: tjal,mpal,mppb' in: query name: orgaos type: string - - description: Categorias a serem pesquisadas + - description: Categorias a serem pesquisadas. Remuneração base (salário), outras + remunerações (benefícios) e descontos enum: - base - outras @@ -961,49 +1059,57 @@ paths: - application/json responses: "200": - description: Requisição bem sucedida. + description: Requisição bem-sucedida com dados de remuneração schema: $ref: '#/definitions/uiapi.searchResponse' "400": - description: Erro de validação dos parâmetros. + description: Erro de validação dos parâmetros de busca schema: type: string "500": - description: Erro interno do servidor. + description: Erro interno do servidor durante processamento da pesquisa schema: type: string tags: - ui_api /uiapi/v2/readme: get: - description: Retorna um README sobre o pacote de dados + description: |- + Recupera o arquivo README com informações sobre o conjunto de dados. Permite filtrar o README com base em parâmetros opcionais de ano, mês e órgão + + Comportamentos: + - Se nenhum filtro for aplicado, retorna o README original + - Com filtro de órgão, gera um README com observações específicas sobre potenciais falhas nos dados operationId: DownloadReadme parameters: - - description: Ano a ser filtrado + - default: "2024" + description: Ano para filtragem dos dados in: query name: ano type: string - - description: Mês a ser filtrado + - default: "12" + description: Mês para filtragem dos dados in: query name: mes type: string - - description: Orgão a ser filtrado + - default: tjrr + description: 'Sigla do órgão para filtragem. Ex.: tjal, mppb, mpdft' in: query name: orgao type: string produces: - - application/json + - text/plain responses: "200": - description: OK + description: README.txt com conteúdo detalhado schema: type: string "400": - description: Parâmetro ano/mês inválido + description: Erro de validação de parâmetros (ano/mês inválidos) schema: type: string "500": - description: Algo deu errado ao retornar o README + description: Erro interno ao processar o README schema: type: string tags: diff --git a/papi/handlers.go b/papi/handlers.go index 7c1d6cff..4ec26126 100644 --- a/papi/handlers.go +++ b/papi/handlers.go @@ -733,7 +733,7 @@ func (h handler) V2GetAggregateIndexesWithParamsByYearAndMonth(c echo.Context) e // @Param detalhe query boolean false "Define se os metadados utilizados para calcular o índice serão retornados ou não." // @Success 200 {object} []aggregateIndexesByGroup "Requisição bem sucedida." // @Failure 500 {string} string "Erro interno do servidor." -// @Router /v2/indice [get] +// @Router /v2/indice [get] func (h handler) V2GetAggregateIndexes(c echo.Context) error { agregado := c.QueryParam("agregado") detalhe := c.QueryParam("detalhe") diff --git a/uiapi/handlers.go b/uiapi/handlers.go index 5cbabe54..25cc53f2 100644 --- a/uiapi/handlers.go +++ b/uiapi/handlers.go @@ -83,15 +83,28 @@ func (h handler) GetSummaryOfAgency(c echo.Context) error { // @ID GetSummaryOfAgency // @Tags ui_api -// @Description Resume os dados de remuneração mensal de um órgão. +// @Description Endpoint de resumo financeiro dos órgãos. Fornece uma análise financeira abrangente para um órgão específico em um mês e ano determinados +// @Description +// @Description Informações Financeiras Detalhadas: +// @Description - Remuneração base total e máxima +// @Description - Outras remunerações e benefícios +// @Description - Valor total de descontos +// @Description - Contagem de membros +// @Description - Análise de rubricas (penduricalhos) específicas +// @Description +// @Description Contexto Adicional: +// @Description - Marcadores de existência de dados anteriores/posteriores ao ano/mês consultados +// @Description - Timestamp da coleta de dados +// @Description - Detalhamento de diferentes tipos de remuneração (remuneração base, outras remunerações e descontos) // @Produce json -// @Param orgao path string true "ID do órgão. Exemplos: tjal, tjba, mppb." -// @Param ano path int true "Ano da remuneração. Exemplo: 2018." -// @Param mes path int true "Mês da remuneração. Exemplo: 1." -// @Success 200 {object} v2AgencySummary "Requisição bem sucedida." -// @Failure 404 {string} string "Órgão não encontrado." -// @Failure 400 {string} string "Parâmetro ano, mês ou nome do órgão são inválidos." -// @Router /uiapi/v2/orgao/resumo/{orgao}/{ano}/{mes} [get] +// @Param orgao path string true "Sigla do órgão. Ex.: tjal, mppb, tjmmg" +// @Param mes path string true "Mês de referência (1-12)" +// @Param ano path string true "Ano de referência" +// @Success 200 {object} v2AgencySummary "Resumo financeiro do órgão processado com sucesso" +// @Failure 400 {string} string "Erro de validação dos parâmetros de entrada" +// @Failure 404 {string} string "Órgão ou dados não encontrados" +// @Failure 500 {string} string "Erro interno durante processamento da consulta" +// @Router /uiapi/v2/orgao/resumo/{orgao}/{ano}/{mes} [get] func (h handler) V2GetSummaryOfAgency(c echo.Context) error { year, err := strconv.Atoi(c.Param("ano")) if err != nil { @@ -180,15 +193,32 @@ func (h handler) GetSalaryOfAgencyMonthYear(c echo.Context) error { // @ID GetSalaryOfAgencyMonthYear // @Tags ui_api -// @Description Busca dados das remunerações mensais de um órgão. +// @Description Endpoint de análise detalhada de remunerações dos órgãos. Recupera informações financeiras granulares para um órgão específico em um mês e ano determinados +// @Description +// @Description Informações Fornecidos: +// @Description - Remuneração máxima no período +// @Description - Histograma de distribuição de rendimentos +// @Description - Metadados do pacote de dados +// @Description +// @Description Histograma de Distribuição de Rendimentos: +// @Description +// @Description O histograma apresenta a quantidade de membros que receberam diferentes faixas de remunerações em um determinado mês. +// @Description As faixas de remuneração são definidas da seguinte forma: +// @Description - 10000: quantidade de membros que receberam até R$ 10.000,00 +// @Description - 20000: quantidade de membros que receberam entre R$ 10.000,01 e R$ 20.000,00 +// @Description - 30000: quantidade de membros que receberam entre R$ 20.000,01 e R$ 30.000,00 +// @Description - 40000: quantidade de membros que receberam entre R$ 30.000,01 e R$ 40.000,00 +// @Description - 50000: quantidade de membros que receberam entre R$ 40.000,01 e R$ 50.000,00 +// @Description - -1: quantidade de membros que receberam acima de R$ 50.000,01 // @Produce json -// @Param orgao path string true "ID do órgão. Exemplos: tjal, tjba, mppb." -// @Param mes path string true "Mês da remuneração. Exemplos: 01, 02, 03..." -// @Param ano path string true "Ano da remuneração. Exemplos: 2018, 2019, 2020..." -// @Success 200 {object} agencyRemuneration "Requisição bem sucedida." -// @Success 206 {object} v2ProcInfoResult "Requisição bem sucedida, mas os dados do órgão não foram bem processados" -// @Failure 400 {string} string "Parâmetros inválidos." -// @Router /uiapi/v2/orgao/salario/{orgao}/{ano}/{mes} [get] +// @Param orgao path string true "Sigla do órgão. Ex.: tjal, mppb, tjmmg" +// @Param mes path string true "Mês de referência (1-12)" +// @Param ano path string true "Ano de referência" +// @Success 200 {object} agencyRemuneration "Dados de remuneração processados com sucesso" +// @Success 206 {object} v2ProcInfoResult "Dados coletados com informações de processamento" +// @Failure 400 {string} string "Erro de validação dos parâmetros de entrada" +// @Failure 500 {string} string "Erro interno durante processamento da consulta" +// @Router /uiapi/v2/orgao/salario/{orgao}/{ano}/{mes} [get] func (h handler) V2GetSalaryOfAgencyMonthYear(c echo.Context) error { month, err := strconv.Atoi(c.Param("mes")) if err != nil { @@ -303,13 +333,26 @@ func (h handler) GetTotalsOfAgencyYear(c echo.Context) error { // @ID GetTotalsOfAgencyYear // @Tags ui_api -// @Description Busca os dados de remuneração de um órgão em um ano específico. +// @Description Recupera dados financeiros detalhados para um órgão em um ano específico +// @Description +// @Description Dados Financeiros Mensais: +// @Description - Remuneração base +// @Description - Outras remunerações e benefícios +// @Description - Descontos +// @Description - Contagem de membros +// @Description +// @Description Métricas Adicionais: +// @Description - Médias per capita +// @Description - Detalhamento de rubricas (auxílios, férias, gratificações) +// @Description - Informações gerais sobre o órgão pesquisado +// @Description - Informações sobre o pacote de dados (URL para download, hash, tamanho) // @Produce json -// @Param orgao path string true "ID do órgão. Exemplos: tjal, tjba, mppb." -// @Param ano path int true "Ano. Exemplo: 2018." -// @Success 200 {object} v2AgencyTotalsYear "Requisição bem sucedida." -// @Failure 400 {string} string "Parâmetro ano ou orgao inválido." -// @Router /uiapi/v2/orgao/totais/{orgao}/{ano} [get] +// @Param orgao path string true "Identificador do órgão público" example:"tjal" +// @Param ano path int true "Ano de referência para a consulta" example:"2022" +// @Success 200 {object} v2AgencyTotalsYear "Dados financeiros completos do órgão no ano especificado" +// @Failure 400 {string} string "Erro de validação: parâmetros de órgão ou ano inválidos" +// @Failure 500 {string} string "Erro interno durante processamento da consulta" +// @Router /uiapi/v2/orgao/totais/{orgao}/{ano} [get] func (h handler) V2GetTotalsOfAgencyYear(c echo.Context) error { year, err := strconv.Atoi(c.Param("ano")) if err != nil { @@ -592,9 +635,9 @@ func (h handler) GetGeneralRemunerationFromYear(c echo.Context) error { // @ID GetGeneralRemunerationFromYear // @Tags ui_api -// @Description Busca os dados, das remunerações de um ano inteiro, agrupados por mês. +// @Description Busca os dados, das remunerações (remuneração base/salário, outras remunerações/benefícios, descontos) e benefícios identificados (rubricas/penduricalhos) de um ano inteiro, agrupados por mês. // @Produce json -// @Param ano path string true "Ano da remuneração. Exemplos: 2018, 2019, 2020..." +// @Param ano path string true "Ano da remuneração. Ex.: 2018, 2019, 2020..." // @Success 200 {object} []mensalRemuneration "Requisição bem sucedida." // @Failure 400 {string} string "Parâmetro ano inválido." // @Failure 500 {string} string "Erro interno." @@ -672,7 +715,7 @@ func (h handler) GeneralSummaryHandler(c echo.Context) error { // @ID GetGeneralSummary // @Tags ui_api -// @Description Busca e resume os dados das remunerações de todos os anos +// @Description Busca e resume os dados das remunerações de todos os anos, trazendo o número de órgão participantes das tetativas de coleta (inclue os órgãos da coleta automatizada, coleta manual e órgãos não coletados, mas que armazenamos alguma informação), número total de meses coletados, data do primeiro e último mês coletado e o valor total de remuneração considerando todos os meses. // @Produce json // @Success 200 {object} generalSummary "Requisição bem sucedida." // @Failure 500 {string} string "Erro interno do servidor." @@ -714,15 +757,31 @@ func (h handler) GetGeneralSummary(c echo.Context) error { // @ID SearchByUrl // @Tags ui_api -// @Description Faz uma busca por remunerações a partir de filtros +// @Description Endpoint de busca avançada para remunerações de servidores públicos +// @Description +// @Description Permite realizar pesquisas detalhadas nas remunerações de servidores públicos com múltiplos filtros flexíveis: +// @Description +// @Description - Filtragem por anos específicos +// @Description - Seleção de meses específicos +// @Description - Pesquisa por órgãos públicos de diferentes esferas +// @Description - Categorias de remuneração +// @Description +// @Description Características principais: +// @Description - Suporta múltiplas seleções em cada filtro +// @Description - Permite combinações complexas de busca +// @Description - Retorna dados consolidados de remuneração dos contracheques por membros +// @Description +// @Description Casos de uso: +// @Description - Análise comparativa de remunerações entre diferentes órgãos +// @Description - Análise análise granular das remunerações por membros dos órgãos // @Produce json -// @Param anos query string false "Anos a serem pesquisados, separados por virgula. Exemplo: 2018,2019,2020" -// @Param meses query string false "Meses a serem pesquisados, separados por virgula. Exemplo: 1,2,3" -// @Param orgaos query string false "Orgãos a serem pesquisados, separados por virgula. Exemplo: tjal,mpal,mppb" -// @Param categorias query string false "Categorias a serem pesquisadas" Enums(base,outras,descontos) -// @Success 200 {object} searchResponse "Requisição bem sucedida." -// @Failure 400 {string} string "Erro de validação dos parâmetros." -// @Failure 500 {string} string "Erro interno do servidor." +// @Param anos query string false "Lista de anos a serem pesquisados, separados por virgula. Exemplo: 2018,2019,2020" +// @Param meses query string false "Lista de meses a serem pesquisados, separados por virgula. Exemplo: 1,2,3" +// @Param orgaos query string false "Lista de órgãos a serem pesquisados, separados por virgula. Exemplo: tjal,mpal,mppb" +// @Param categorias query string false "Categorias a serem pesquisadas. Remuneração base (salário), outras remunerações (benefícios) e descontos" Enums(base,outras,descontos) +// @Success 200 {object} searchResponse "Requisição bem-sucedida com dados de remuneração" +// @Failure 400 {string} string "Erro de validação dos parâmetros de busca" +// @Failure 500 {string} string "Erro interno do servidor durante processamento da pesquisa" // @Router /uiapi/v2/pesquisar [get] func (h handler) SearchByUrl(c echo.Context) error { //Pegando os query params @@ -764,12 +823,23 @@ func (h handler) SearchByUrl(c echo.Context) error { // @ID DownloadByUrl // @Tags ui_api -// @Description Baixa dados referentes a remunerações a partir de filtros +// @Description Baixa um arquivo csv referentes a remunerações a partir de filtros. O arquivo tem um limite de 10 mil linhas. Para cada parâmetro, é possível passar múltiplos valores separados por vírgula. As colunas do arquivo csv são: +// @Description +// @Description - Nome do órgão +// @Description - Mês de referência do contracheque +// @Description - Ano de referência do contracheque +// @Description - Matrícula do membro (identificador único do membro no órgão) +// @Description - Nome do membro +// @Description - Cargo que o membro exerce no órgão +// @Description - Lotação (unidade na qual o membro do órgão desenvolve suas atividades) +// @Description - Categoria do contracheque (base, outras remunerações ou descontos) +// @Description - Detalhamento do contracheque (ex: subsídio, desconto, benefício, etc) +// @Description - Valor do contracheque em reais, não corrigido pela inflação // @Produce json // @Param anos query string false "Anos a serem pesquisados, separados por virgula. Exemplo: 2018,2019,2020" // @Param meses query string false "Meses a serem pesquisados, separados por virgula. Exemplo: 1,2,3" // @Param orgaos query string false "Orgãos a serem pesquisados, separados por virgula. Exemplo: tjal,mpal,mppb" -// @Param categorias query string false "Categorias a serem pesquisadas" Enums(base,outras,descontos) +// @Param categorias query string false "Categorias a serem pesquisadas. Se nada for informado, todas as categorias serão baixadas" Enums(base,outras,descontos) // @Success 200 {file} file "Arquivo CSV com os dados." // @Failure 400 {string} string "Erro de validação dos parâmetros." // @Failure 500 {string} string "Erro interno do servidor." @@ -808,14 +878,18 @@ func (h handler) DownloadByUrl(c echo.Context) error { // @ID DownloadReadme // @Tags ui_api -// @Description Retorna um README sobre o pacote de dados -// @Produce json -// @Param ano query string false "Ano a ser filtrado" -// @Param mes query string false "Mês a ser filtrado" -// @Param orgao query string false "Orgão a ser filtrado" -// @Success 200 {string} text/plain "Requisição bem sucedida." -// @Failure 400 {string} string "Parâmetro ano/mês inválido" -// @Failure 500 {string} string "Algo deu errado ao retornar o README" +// @Description Recupera o arquivo README com informações sobre o conjunto de dados. Permite filtrar o README com base em parâmetros opcionais de ano, mês e órgão +// @Description +// @Description Comportamentos: +// @Description - Se nenhum filtro for aplicado, retorna o README original +// @Description - Com filtro de órgão, gera um README com observações específicas sobre potenciais falhas nos dados +// @Produce text/plain +// @Param ano query string false "Ano para filtragem dos dados" default(2024) +// @Param mes query string false "Mês para filtragem dos dados" default(12) +// @Param orgao query string false "Sigla do órgão para filtragem. Ex.: tjal, mppb, mpdft" default(tjrr) +// @Success 200 {string} string "README.txt com conteúdo detalhado" +// @Failure 400 {string} string "Erro de validação de parâmetros (ano/mês inválidos)" +// @Failure 500 {string} string "Erro interno ao processar o README" // @Router /uiapi/v2/readme [get] func (h handler) DownloadReadme(c echo.Context) error { readmeFile := "uiapi/readme_content.txt" @@ -890,7 +964,12 @@ func (h handler) DownloadReadme(c echo.Context) error { // @ID GetAnnualSummary // @Tags ui_api -// @Description Retorna os dados anuais de um orgão +// @Description Retorna os dados de remuneração de todos os anos disponíveis para um órgão específico, incluindo: +// @Description - Remuneração base/salário, outras remunerações/benefícios, descontos e remuneração líquida (salário+benefícios-descontos). Dados brutos, agrupados por mês e per capita +// @Description - Quantidade de meses com dados no determinado ano +// @Description - Quantidade média de membros do órgão naquele ano +// @Description - Resumo dos benefícios identificados (rubricas/penduricalhos) e seus respectivos valores no ano +// @Description - Informações do pacote de dados, URL do pacote de dados para download, seu hash e tamanho do pacote de dados (em bytes) // @Produce json // @Param orgao path string true "Nome do orgão" // @Success 200 {object} []annualSummary "Requisição bem sucedida." From a6913343f12118127e8c95e72b003b23a2f1508f Mon Sep 17 00:00:00 2001 From: JezzDiego Date: Sat, 12 Apr 2025 11:08:37 -0300 Subject: [PATCH 6/7] docs: update endpoint descriptions for financial summaries --- docs/docs.go | 2 +- docs/swagger.json | 2 +- docs/swagger.yaml | 2 +- papi/handlers.go | 2 +- uiapi/handlers.go | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs.go b/docs/docs.go index 45c3e1cb..287c6960 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -197,7 +197,7 @@ const docTemplate = `{ }, "/uiapi/v2/orgao/resumo/{orgao}/{ano}/{mes}": { "get": { - "description": "Endpoint de resumo financeiro dos órgãos. Fornece uma análise financeira abrangente para um órgão específico em um mês e ano determinados\n\nInformações Financeiras Detalhadas:\n- Remuneração base total e máxima\n- Outras remunerações e benefícios\n- Valor total de descontos\n- Contagem de membros\n- Análise de rubricas (penduricalhos) específicas\n\nContexto Adicional:\n- Marcadores de existência de dados anteriores/posteriores ao ano/mês consultados\n- Timestamp da coleta de dados\n- Detalhamento de diferentes tipos de remuneração (remuneração base, outras remunerações e descontos)", + "description": "Endpoint de resumo das remunerações mensal de um órgão. Fornece uma análise financeira abrangente para um órgão específico em um mês e ano determinados\n\nInformações Financeiras Detalhadas:\n- Remuneração base total e máxima\n- Outras remunerações e benefícios\n- Valor total de descontos\n- Contagem de membros\n- Análise de rubricas (penduricalhos) específicas\n\nContexto Adicional:\n- Marcadores de existência de dados anteriores/posteriores ao ano/mês consultados\n- Timestamp da coleta de dados\n- Detalhamento de diferentes tipos de remuneração (remuneração base, outras remunerações e descontos)", "produces": [ "application/json" ], diff --git a/docs/swagger.json b/docs/swagger.json index 704351c2..0fe20590 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -188,7 +188,7 @@ }, "/uiapi/v2/orgao/resumo/{orgao}/{ano}/{mes}": { "get": { - "description": "Endpoint de resumo financeiro dos órgãos. Fornece uma análise financeira abrangente para um órgão específico em um mês e ano determinados\n\nInformações Financeiras Detalhadas:\n- Remuneração base total e máxima\n- Outras remunerações e benefícios\n- Valor total de descontos\n- Contagem de membros\n- Análise de rubricas (penduricalhos) específicas\n\nContexto Adicional:\n- Marcadores de existência de dados anteriores/posteriores ao ano/mês consultados\n- Timestamp da coleta de dados\n- Detalhamento de diferentes tipos de remuneração (remuneração base, outras remunerações e descontos)", + "description": "Endpoint de resumo das remunerações mensal de um órgão. Fornece uma análise financeira abrangente para um órgão específico em um mês e ano determinados\n\nInformações Financeiras Detalhadas:\n- Remuneração base total e máxima\n- Outras remunerações e benefícios\n- Valor total de descontos\n- Contagem de membros\n- Análise de rubricas (penduricalhos) específicas\n\nContexto Adicional:\n- Marcadores de existência de dados anteriores/posteriores ao ano/mês consultados\n- Timestamp da coleta de dados\n- Detalhamento de diferentes tipos de remuneração (remuneração base, outras remunerações e descontos)", "produces": [ "application/json" ], diff --git a/docs/swagger.yaml b/docs/swagger.yaml index c5124ebf..16b60011 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -855,7 +855,7 @@ paths: /uiapi/v2/orgao/resumo/{orgao}/{ano}/{mes}: get: description: |- - Endpoint de resumo financeiro dos órgãos. Fornece uma análise financeira abrangente para um órgão específico em um mês e ano determinados + Endpoint de resumo das remunerações mensal de um órgão. Fornece uma análise financeira abrangente para um órgão específico em um mês e ano determinados Informações Financeiras Detalhadas: - Remuneração base total e máxima diff --git a/papi/handlers.go b/papi/handlers.go index 4ec26126..ba4b17ab 100644 --- a/papi/handlers.go +++ b/papi/handlers.go @@ -733,7 +733,7 @@ func (h handler) V2GetAggregateIndexesWithParamsByYearAndMonth(c echo.Context) e // @Param detalhe query boolean false "Define se os metadados utilizados para calcular o índice serão retornados ou não." // @Success 200 {object} []aggregateIndexesByGroup "Requisição bem sucedida." // @Failure 500 {string} string "Erro interno do servidor." -// @Router /v2/indice [get] +// @Router /v2/indice [get] func (h handler) V2GetAggregateIndexes(c echo.Context) error { agregado := c.QueryParam("agregado") detalhe := c.QueryParam("detalhe") diff --git a/uiapi/handlers.go b/uiapi/handlers.go index 25cc53f2..be0703ea 100644 --- a/uiapi/handlers.go +++ b/uiapi/handlers.go @@ -83,7 +83,7 @@ func (h handler) GetSummaryOfAgency(c echo.Context) error { // @ID GetSummaryOfAgency // @Tags ui_api -// @Description Endpoint de resumo financeiro dos órgãos. Fornece uma análise financeira abrangente para um órgão específico em um mês e ano determinados +// @Description Endpoint de resumo das remunerações mensal de um órgão. Fornece uma análise financeira abrangente para um órgão específico em um mês e ano determinados // @Description // @Description Informações Financeiras Detalhadas: // @Description - Remuneração base total e máxima From 9cc94f002532ccbcb78099a338a97fea5241ca00 Mon Sep 17 00:00:00 2001 From: JezzDiego Date: Wed, 16 Apr 2025 11:08:42 -0300 Subject: [PATCH 7/7] docs: enhance descriptions for group endpoint --- docs/docs.go | 2 +- docs/swagger.json | 2 +- docs/swagger.yaml | 5 ++++- papi/handlers.go | 2 +- uiapi/handlers.go | 2 +- 5 files changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/docs.go b/docs/docs.go index 287c6960..7b8dd4c3 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -367,7 +367,7 @@ const docTemplate = `{ }, "/uiapi/v2/orgao/{grupo}": { "get": { - "description": "Busca os órgãos de um determinado grupo.", + "description": "Busca informações de id (sigla), nome e entidade (jurisdiçãso) de um determinado grupo de órgãos. Ao Selecionar um grupo de órgãos por estado (Ex.: RJ, SP, etc.), retorna as informações dos tribunais de justiça desse estado (entidade=Tribunal).", "produces": [ "application/json" ], diff --git a/docs/swagger.json b/docs/swagger.json index 0fe20590..eb5fd4b5 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -358,7 +358,7 @@ }, "/uiapi/v2/orgao/{grupo}": { "get": { - "description": "Busca os órgãos de um determinado grupo.", + "description": "Busca informações de id (sigla), nome e entidade (jurisdiçãso) de um determinado grupo de órgãos. Ao Selecionar um grupo de órgãos por estado (Ex.: RJ, SP, etc.), retorna as informações dos tribunais de justiça desse estado (entidade=Tribunal).", "produces": [ "application/json" ], diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 16b60011..be23db59 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -792,7 +792,10 @@ paths: - ui_api /uiapi/v2/orgao/{grupo}: get: - description: Busca os órgãos de um determinado grupo. + description: 'Busca informações de id (sigla), nome e entidade (jurisdiçãso) + de um determinado grupo de órgãos. Ao Selecionar um grupo de órgãos por estado + (Ex.: RJ, SP, etc.), retorna as informações dos tribunais de justiça desse + estado (entidade=Tribunal).' operationId: GetBasicInfoOfType parameters: - description: Grupo de órgãos diff --git a/papi/handlers.go b/papi/handlers.go index ba4b17ab..00ecbcf4 100644 --- a/papi/handlers.go +++ b/papi/handlers.go @@ -733,7 +733,7 @@ func (h handler) V2GetAggregateIndexesWithParamsByYearAndMonth(c echo.Context) e // @Param detalhe query boolean false "Define se os metadados utilizados para calcular o índice serão retornados ou não." // @Success 200 {object} []aggregateIndexesByGroup "Requisição bem sucedida." // @Failure 500 {string} string "Erro interno do servidor." -// @Router /v2/indice [get] +// @Router /v2/indice [get] func (h handler) V2GetAggregateIndexes(c echo.Context) error { agregado := c.QueryParam("agregado") detalhe := c.QueryParam("detalhe") diff --git a/uiapi/handlers.go b/uiapi/handlers.go index be0703ea..31d73c28 100644 --- a/uiapi/handlers.go +++ b/uiapi/handlers.go @@ -542,7 +542,7 @@ func (h handler) GetBasicInfoOfType(c echo.Context) error { // @ID GetBasicInfoOfType // @Tags ui_api -// @Description Busca os órgãos de um determinado grupo. +// @Description Busca informações de id (sigla), nome e entidade (jurisdiçãso) de um determinado grupo de órgãos. Ao Selecionar um grupo de órgãos por estado (Ex.: RJ, SP, etc.), retorna as informações dos tribunais de justiça desse estado (entidade=Tribunal). // @Produce json // @Param grupo path string false "Grupo de órgãos" Enums(justica-eleitoral, ministerios-publicos, justica-estadual, justica-do-trabalho, justica-federal, justica-militar, justica-superior, conselhos-de-justica, AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO) // @Success 200 {object} state "Órgãos do grupo"