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, escolha ativar a digitalização de anotação e implemente seus aplicativos 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, são 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 MicroProfile OpenAPI com Liberty, consulte o website Open Liberty

Antes de Começar

Saiba sobre a OpenAPI V3 specification. Use arquivos YAML ou JSON para documentar as APIs RESTful em seus aplicativos.

É possível usar as interfaces Java e os modelos de programação que estão disponíveis no MicroProfile OpenAPI Specification 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 mais recentes, consulte Gerando a 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 um aplicativo RESTful usando anotações OpenAPI no código Java™ usando Aplicativo de amostra de anotação OpenAPI V3.
Veja um exemplo de um documento OpenAPI V3 no formato YAML criado com um editor de textos com OpenAPI V3 documento de exemplo.
Estenda o recurso openapi-3.0 usando as interfaces de programação io.swagger.oas.integration.OpenAPIConfigurationBuilder 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 as anotações OpenAPI no código Java para aumentar 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 seus recursos e exemplos de seu uso, consulte OpenAPI V3 interfaces de programação.
Habilite o recurso openapi-3.0 na configuração do servidor Liberty .
1. Adicionar o recurso openapi-3.0 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 se um aplicativo não aparece 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>
```
  Nota: O atributo enabled não é suportado para documentos da API REST que são fornecidos por outros recursos do Liberty .
Opcional: Habilita a digitalização de anotação 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 atributo apiTypeVisibility do elemento classloader como visibilidade API de terceiros. Inclua third-party no elemento classloader em seu arquivo server.xml .
  
  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: Ativar validação de documentos do 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 endpoints 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 arquivo server.xml para disponibilizar a documentação da API REST pública 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 entre aplicativos para esse servidor Liberty . O documento está no formato YAML por padrão. Ao visualizar sua documentação com o Microsoft Internet Explorer 11, ele retorna um documento do YAML que não está formatado corretamente Como uma 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: é possível 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.