Compreender a estrutura da documentação

Ao gerar a documentação do Swagger, o sistema Sterling™ Order Management cria uma estrutura de pastas bem organizada que contém especificações JSON, páginas HTML interativas, um arquivo de índice principal e um índice de pesquisa.

A documentação está disponível em runtime/xapidocs/swaggerdoc/.

Pasta JSON (swaggerdoc/JSON/)

A pasta JSON contém arquivos de especificações técnicas da API, tais como ycp.json, ycd.json, e omp.json. Essas definições de API legíveis por máquina são utilizadas em ferramentas e processos de automação.

Casos de uso

  • Gere código cliente em Java, Python, JavaScript, e outras linguagens.
  • Integre-se com plataformas de gerenciamento de API.
  • Configure testes automatizados.

Esses arquivos são utilizados por desenvolvedores, engenheiros de controle de qualidade e especialistas em integração.

Pasta HTML (swaggerdoc/HTML/)

A pasta HTML contém páginas da Web interativas para cada grupo de API, como ycp.html, ycd.html, e omp.html. Estas páginas oferecem documentação de fácil compreensão, com recursos interativos.

Recursos-chave

  • Seções expansíveis : navegue facilmente pelas APIs.
  • Detalhes completos : Veja as descrições dos campos, as tags obrigatórias e os tipos de dados.
  • Exemplos : Analise os pedidos e respostas de amostras.

Desenvolvedores, analistas de negócios, gerentes de projeto, redatores técnicos e qualquer pessoa que precise entender as APIs utilizam estas páginas.

index.html arquivo (swaggerdoc/index.html)

O index.html arquivo é o ponto de entrada principal, com recursos de navegação e pesquisa.

Recursos

  • Botões para cada grupo de API
  • Barra de pesquisa global para localizar APIs em todos os grupos
  • Interface simples para facilitar a navegação

Como Utilizar

  • Clique no botão de um grupo para visualizar suas APIs.
  • Use a barra de pesquisa para encontrar APIs específicas instantaneamente.
  • Marque esta página como seu ponto de partida.

api-index.js arquivo (swaggerdoc/api-index.js)

O api-index.js arquivo é um índice de pesquisa gerado automaticamente que permite o funcionamento da funcionalidade de pesquisa em tempo real. Contém uma lista completa de todas as APIs, incluindo nomes, métodos, grupos e links de navegação.

Observação: O índice de pesquisa é atualizado automaticamente quando você regenera a documentação. Não é necessário fazer nenhuma edição manual.

Melhores práticas

Para aproveitar ao máximo a documentação do Swagger, siga estas práticas recomendadas:

  • Comece com index.html como seu ponto de entrada principal.
  • Use o recurso de pesquisa para encontrar APIs rapidamente em todos os grupos.
  • Importe arquivos JSON para o Postman ou ferramentas semelhantes para testar APIs.
  • Marque como favoritas as páginas HTML dos grupos de API usados com frequência para acesso rápido.
  • Compartilhe a documentação URL com sua equipe de desenvolvimento.

Para obter mais informações, consulte a especificação OpenAPI e o Swagger UI.