A especificação OpenAPI

A especificação OpenAPI, conhecida anteriormente como especificação Swagger, é o padrão do setor para a definição de REST APIs. Quando a Open API Initiative formada recentemente para assumir a custódia da especificação, o Google teve a satisfação de se tornar um dos membros. Acreditamos que especificações abertas são a chave para dar suporte a uma excelente corrente de ferramentas para desenvolvedores.

Benefícios

Além da integração com as ferramentas de Gerenciamento da API como o Endpoints, há muitos motivos para que as equipes adotem a especificação OpenAPI. O principal motivo se refere à documentação. Depois de ter uma especificação OpenAPI para sua API, é fácil adicionar a IU Swagger ao projeto como uma ferramenta de comunicação interativa. Consulte Adição da IU Swagger ao projeto para um guia rápido.

O uso de uma especificação OpenAPI traz muitos outros benefícios. Você pode gerar bibliotecas de cliente em dezenas de linguagens, gerar stubs de servidores, há projetos para verificar a conformidade e a até projetos para gerar exemplos.

Geração de uma especificação OpenAPI

Dependendo da linguagem que está usando, você pode gerar a especificação. No Java, há projetos de código aberto para Jersey e Spring que podem gerar especificações a partir das anotações. Também há um plug-in Maven. O flask-swagger pode ser um projeto interessante para usuários do Python, e o swagger-node-express para desenvolvedores do Node. Consulte o website do Swagger para uma lista completa de integrações.

Recursos incompatíveis da especificação OpenAPI

Por ora, aceitaremos somente os arquivos JSON e YAML da especificação OpenAPI v2.0.

Os recursos da especificação OpenAPI a seguir ainda não são aceitos no Google Cloud Endpoints.

  • Polimorfismo (tipos básicos e derivados)
  • Tipo de arquivo em parâmetro de corpo de operações ({“type”:“file”})
  • Parâmetros do cabeçalho
  • Parâmetros de dados de formulários
  • A operação "Options"
  • A operação "Head"
  • Diferentes objetos de resposta por código de status
  • Referências a tipos fora da especificação ("$ref": "http://mydomain/mytype.json")
  • JSON: typo: null
  • Composição de tipo usando allof
  • collectionFormat
  • Dependências
  • Combinação de políticas de segurança com lógica complexa, como AND e OR, indicando que um método requer (petstore_advance_auth) OR (petstore_auth AND api_key).
  • Restrições no tempo de execução ("allowEmptyValue", "readonly", "required", "enums")
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…