Writing openapi
Describiendo tu API
Hay muchas herramientas excelentes en línea para aprender sobre y construir documentos OpenAPI. Aquí están nuestras favoritas:
- Swagger’s OpenAPI Guidepara familiarizarte con la sintaxis de OpenAPI
- OpenAPI v3.1.0 Specificationpara todos los detalles sobre la especificación más reciente de OpenAPI
- Swagger & OpenAPI Validatorpara depurar tu documento OpenAPI
- Swagger’s Editorpara ver ejemplos en acción
La Guía OpenAPI de Swagger es para OpenAPI v3.0, pero casi toda la información es aplicable a v3.1. Para más información sobre las diferencias entre v3.0 y v3.1, consultaOpenAPI’s blog post.
Especificando la URL para tu API
En un documento OpenAPI, los diferentes endpoints de la API se especifican por sus rutas, como/users/{id}, o tal vez simplemente/. Para especificar la URL base a la que se deben añadir estas rutas, OpenAPI proporciona el camposervers. Este campo es necesario para usar algunas características de Mintlify como el API Playground. Lee cómo configurar el camposerversen ladocumentación de Swagger.
El API Playground utilizará estas URLs de servidor para determinar dónde enviar las solicitudes. Si se especifican múltiples servidores, aparecerá un menú desplegable para permitir alternar entre servidores. Si no se proporciona ningún servidor, el API Playground utilizará el modo simple, ya que no hay forma de enviar una solicitud.
Si diferentes endpoints dentro de tu API existen en diferentes URLs, puedessobrescribir el campo serverpara una ruta u operación específica.
Especificando la autenticación
Casi todas las APIs requieren algún método de autenticación. OpenAPI proporciona el camposecuritySchemespara definir los métodos de autenticación utilizados en toda tu API, con una configuración simple para los tipos de autenticación más comunes -Basic,Bearer, yAPI Keys. Para aplicar estos métodos de autenticación a tus endpoints, OpenAPI utiliza el camposecurity. La sintaxis para definir y aplicar la autenticación es un poco poco intuitiva, así que definitivamente revisala documentación y ejemplos de Swaggersobre el tema.
Las descripciones de la API y el API Playground añadirán campos de autenticación basados en las configuraciones de seguridad en tu documento OpenAPI.
Si diferentes endpoints dentro de tu API requieren diferentes métodos de autenticación, puedessobrescribir el campo securitypara una operación específica.