Writing openapi
Descrevendo sua API
Existem muitas ótimas ferramentas online para aprender sobre e construir documentos OpenAPI. Aqui estão nossas favoritas:
- Swagger’s OpenAPI Guide para se familiarizar com a sintaxe OpenAPI
- OpenAPI v3.1.0 Specificationpara todos os detalhes sobre a mais recente especificação OpenAPI
- Swagger & OpenAPI Validatorpara depurar seu documento OpenAPI
- Swagger’s Editorpara ver exemplos em ação
O Guia OpenAPI do Swagger é para OpenAPI v3.0, mas quase todas as informações são aplicáveis à v3.1. Para mais informações sobre as diferenças entre v3.0 e v3.1, confiraOpenAPI’s blog post.
Especificando a URL para sua API
Em um documento OpenAPI, diferentes endpoints da API são especificados por seus caminhos, como/users/{id}, ou talvez simplesmente/. Para especificar a URL base à qual esses caminhos devem ser anexados, o OpenAPI fornece o camposervers. Este campo é necessário para usar alguns recursos do Mintlify, como o API Playground. Leia como configurar o camposerversnaSwagger documentation.
O API Playground usará essas URLs de servidor para determinar onde enviar as solicitações. Se vários servidores forem especificados, um menu suspenso aparecerá para permitir a alternância entre servidores. Se nenhum servidor for fornecido, o API Playground usará o modo simples, pois não há como enviar uma solicitação.
Se diferentes endpoints dentro da sua API existirem em URLs diferentes, você podesubstituir o campo do servidorpara um determinado caminho ou operação.
Especificando autenticação
Quase todas as APIs requerem algum método de autenticação. O OpenAPI fornece o camposecuritySchemespara definir os métodos de autenticação usados em toda a sua API, com configuração simples para os tipos de autenticação mais comuns -Basic,BearereAPI Keys. Para aplicar esses métodos de autenticação aos seus endpoints, o OpenAPI usa o camposecurity. A sintaxe para definir e aplicar autenticação é um pouco contraintuitiva, então definitivamente confira aSwagger’s documentation and examplessobre o assunto.
As descrições da API e o API Playground adicionarão campos de autenticação com base nas configurações de segurança em seu documento OpenAPI.
Se diferentes endpoints dentro da sua API exigirem diferentes métodos de autenticação, você podesubstituir o campo de segurançapara uma determinada operação.