Gerando a documentação da API REST com o OpenAPI

É possível gerar a documentação da API REST usando o recurso openapi-3.0, que suporta a especificação do OpenAPI. Documente suas APIs REST, especifique APIs públicas e privadas, opte por habilitar a verificação de anotações e implante suas aplicações web em um servidor Liberty. Em seguida, é possível visualizar a documentação da API que é gerada pelo openapi-3.0 em um navegador que usa uma interface com o usuário de fácil compreensão.

Recursos estabilizados: Os recursos OpenAPI V3, openapi-3.0 e openapi-3.1, foram estabilizados. É possível continuar a utilizar os recursos. No entanto, a alternativa estratégica é usar um recurso MicroProfile OpenAPI, como mpOpenAPI-3.0.

Para obter mais informações sobre como usar o MicroProfile OpenAPI com a Liberty, consulte o site Open Liberty.

Antes de Começar

Saiba mais sobre a especificação OpenAPI V3. Use arquivos YAML ou JSON para documentar as APIs RESTful em seus aplicativos.

Você pode usar as interfaces Java e os modelos de programação disponíveis na especificação MicroProfileOpenAPI versão 1.0. O recurso mpOpenAPI-1.0 implementa a especificação do MicroProfile OpenAPI. Para obter mais informações sobre o mpOpenAPI-1.0 e recursos posteriores, consulte Gerando documentação da API REST com o MicroProfile OpenAPI.

Sobre esta Tarefa

É possível explorar esses recursos, como a nova interface com o usuário, anotações e interfaces de programação, com os seguintes aplicativos de amostra.

Tente documentar uma aplicação RESTful usando anotações OpenAPI em código Java™ usando a aplicação de exemplo de anotação OpenAPI V3.
Veja um exemplo de um documento OpenAPI V3 no formato YAML criado com um editor de texto com OpenAPI V3 documento de exemplo.
Amplie o openapi-3.0 recurso usando as interfaces io.swagger.oas.integration.OpenAPIConfigurationBuilder de programação com o exemplo de interface de programação OpenAPIConfiguration.

Procedimento

Construa a documentação do OpenAPI.
É possível documentar e construir OpenAPIs de várias maneiras:
- Especifique anotações de OpenAPI o no código Java para ampliar e documentar um aplicativo.
- Use um editor de texto para documentar a API com tags do OpenAPI e, em seguida, coloque o arquivo concluído openapi.yaml, openapi.yml ou openapi.json no diretório META-INF de seu aplicativo.
- Use as interfaces de programação io.swagger.oas.integration.OpenAPIConfigurationBuilder para construir o modelo do OpenAPI a partir do aplicativo. Esta interface e as outras interfaces de programação relacionadas para o OpenAPI V3 podem ser localizadas nos arquivos JAR no diretório /wlp/dev/api/third-party. Para que o recurso openapi-3.0 inicie o OpenAPIConfigurationBuilder, o archive do aplicativo deve ter um arquivo META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder. O conteúdo desse arquivo é o nome completo do OpenAPIConfigurationBuilder.
  Para obter mais informações sobre as interfaces de programação disponíveis, descrições de suas capacidades e exemplos de uso, consulte OpenAPI V3 interfaces de programação.
Habilite o openapi-3.0 recurso na configuração do servidor Liberty.
1. Adicione o openapi-3.0 recurso ao gerenciador de recursos.
```
<server>
   <featureManager>
      <feature>openapi-3.0</feature>
   </featureManager>
</server>
```
2. Opcional: especifique que um aplicativo OpenAPI é privado.
  
  Por padrão, a documentação do OpenAPI é pública. Todos os usuários podem acessar APIs públicas, muitas vezes sem autenticação. As APIs públicas são documentadas no recurso /api/docs.
  É possível especificar que as APIs permaneçam privadas. As APIs para uso administrativo geralmente são mantidas privadas. As APIs privadas, que usam senhas para proteção, são documentadas no recurso /ibm/api/docs. Este recurso documenta todas as APIs privadas e todas as APIs públicas.
  
  É possível especificar APIs privadas para aplicativos da web de duas maneiras:
  - Use webModuleDoc na configuração do servidor, com o atributo public configurado como false.
    1. Inclua um elemento openapi e configure seu atributo booleano enablePrivateURL como true.
    2. Inclua um subelemento webModuleDoc para cada aplicativo da web e configure seu atributo booleano public como true para APIs públicas e como false para APIs privadas.
    O exemplo a seguir torna visíveis os OpenAPIs do aplicativo airlines e desativa a exposição dos OpenAPIs do aplicativo airlinesAdmin.
```
<openapi enablePrivateURL="true">
  <webModuleDoc contextRoot="/airlines" public="true" />
  <webModuleDoc contextRoot="/airlinesAdmin" public="false" />
</openapi>
```
    Por padrão, o atributo public de webModuleDoc é configurado como true. Esta configuração é necessária apenas para desativar os aplicativos que você deseja manter privados.
  - Use uma palavra-chave de extensão do fornecedor na descrição da API para designar que uma API é privada.
    1. Inclua um elemento openapi na configuração do servidor e configure seu atributo booleano enablePrivateURL como true.
    2. Coloque a palavra-chave e o valor x-ibm-private: true no arquivo META-INF/openapi.yaml do documento de descrição da API ou no arquivo de outro formato suportado. Este valor substitui a visibilidade padrão da API e pode ser substituído por uma entrada webModuleDoc.
3. Opcional: especifique que um aplicativo não apareça no documento OpenAPI.
  
  Por padrão, seus módulos da web que contêm documentos da API de REST aparecem no documento OpenAPI mesclado disponível no recurso /api/docs. Para evitar que os módulos da web apareçam no documento do OpenAPI, mude os atributos do elemento webModuleDoc na configuração do servidor.
  Identifique o módulo da web que você deseja ocultar ou exibir com o atributo contextRoot. Em seguida, mude o atributo enabled para false para ocultar o módulo da web do documento do OpenAPI. O valor padrão para o atributo enabled é true. No exemplo a seguir, o módulo airlines é configurado para que apareça no documento da OpenAPI, enquanto o módulo airlinesAdmin está oculto.
```
<openapi>
  <webModuleDoc contextRoot="/airlines" enabled="true" />
  <webModuleDoc contextRoot="/airlinesAdmin" enabled="false" />
</openapi>
```
  Observação: o enabled atributo não é compatível com documentos da API REST fornecidos por outros recursos do Liberty.
Opcional: habilite a verificação de anotações JAX-RS.

Inclua o recurso jaxrs-2.0 no gerenciador de recursos. Quando os recursos jaxrs-2.0 e openapi-3.0 estiverem ativados em um servidor, o scanner de anotação varrerá todos os aplicativos da web que estão implementados no servidor, a menos que a configuração do servidor desative a varredura. O scanner passa por classes que são anotadas com as anotações do OpenAPI 3.0 na definição de classe e anotadas com a anotação @Path do JAX-RS. É possível acessar documentos do OpenAPI gerados com o terminal público do OpenAPI (api/docs) e o terminal privado (ibm/api/docs).
Permita a visibilidade da API de terceiros para aplicativos específicos.
Para ativar o carregamento de tempo de execução de anotações, modelo e modelos de programação do OpenAPI, deve-se ativar a visibilidade da API de terceiros para o aplicativo específico.
1. Defina o apiTypeVisibility atributo do classloader elemento como visibilidade da API de terceiros. Adicione third-party ao classloader elemento no seu server.xml arquivo.
  
  Se você não especificar classloader para incluir third-party no apiTypeVisibility, ele usará a definição padrão de spec, stable e ibm-api.
```
<application id="scholar" name="Scholar" type="ear" location="scholar.ear">
  <classloader apiTypeVisibility="spec, ibm-api, stable, third-party" commonLibraryRef="Alexandria" />
</application>
```
Opcional: habilite a validação de documentos OpenAPI.

A capacidade de validação é desativada por padrão. Ao ativar a validação, cada documento do OpenAPI fornecido pelo aplicativo é validado com relação às restrições declaradas na especificação do OpenAPI V3 pelo recurso openapi-3.0. Se openapi-3.0 localizar um documento do OpenAPI que não é válido, o recurso relatará um erro nos logs para cada restrição violada. O documento inválido é excluído do documento do OpenAPI agregado que é retornado pelo terminal api/docs. Para ativar a validação, configure o atributo validation como true no arquivo server.xml.
```
<openapi validation="true"/>
```
Implemente seus aplicativos.
Visualize o documento da API gerado em um navegador.
É possível localizar seu documento da API gerado no terminal /api/docs usando uma das URLs a seguir, dependendo se a sua API é pública ou privada.
- Para APIs públicas não SSL, visualize seu documento em http://Liberty_host:http_port/api/docs.
- Para APIs públicas SSL, visualize seu documento em https://Liberty_host:https_port/api/docs.
- Para APIs privadas SSL, visualize seu documento em https://Liberty_host:https_port/ibm/api/docs.
Dica: Por padrão, dois pontos finais estão disponíveis para um servidor.
- GET http://Liberty_host:http_port/api/docs
- GET http://Liberty_host:http_port/api/explorer
É possível customizar URLs para terminais públicos com o atributo publicURL no arquivo server.xml. O exemplo a seguir ilustra a configuração no server.xml arquivo para disponibilizar a documentação pública da API REST com GET http://Liberty_host:http_port/myAPI/docs and http://Liberty_host:http_port/myAPI/explorer.
```
<openapi publicURL="myAPI" />
```
O documento OpenAPI é gerado e agregado em todas as aplicações para esse servidor Liberty. O documento está no formato YAML por padrão. Quando você visualiza sua documentação com o Microsoft Internet Explorer 11, ele retorna um documento YAML que não está formatado corretamente. Como solução alternativa, use um navegador como Mozilla, Firefox ou Google Chrome. Se a solicitação http tiver um cabeçalho Accept com um valor application/json, o documento estará no formato JSON.

Dica: você pode filtrar o documento OpenAPI por raiz de contexto. O terminal público (api/docs) e o terminal privado (ibm/api/docs) suportam um parâmetro de consulta, root, que pode filtrar as raízes de contexto localizadas. Por exemplo, uma chamada para GET http://Liberty_host:http_port/api/docs?root=/myApp recupera um documento do OpenAPI V3 que tem somente a documentação para a raiz de contexto myApp.

Resultados

A Interface com o usuário do OpenAPI renderiza as definições agregadas de /api/docs para exibir uma UI de fácil compreensão em http://Liberty_host:http_port/api/explorer. Se você ativar SSL, poderá acessar a UI protegida em https://Liberty_host:https_port/api/explorer.

É possível procurar os módulos da web privados ativando o atributo enablePrivateURL no elemento openAPI do arquivo server.xml.

<openapi enablePrivateURL="true"/>

Quando a procura do módulo da web privado estiver ativada, use https://Liberty_host:https_port/ibm/api/explorer para exibir a UI de fácil compreensão para módulos da web públicos e privados.

É possível visualizar todos os terminais RESTful de seu aplicativo nesta interface com o usuário. Também é possível filtrar os terminais exibidos para focalizar em aplicativos específicos.