Especificación de interfaz OpenAPI
OpenAPI es una forma estándar de describir las API HTTP. Hoy, hablemos de la especificación de su interfaz ( Especificación OpenAPI (versión china) )~
Especificación del número de versión de OpenAPI
El número de versión de OpenAPI se define usando el formato de major.minor.patch, como 3.1.2
- major: especifica la versión principal
- minor: especifica la versión menor
- parche: especifica el parche en la versión menor
Especificación de formato OpenAPI
OpenAPI puede usar formato JSON o YAML, y los campos distinguen entre mayúsculas y minúsculas:
ejemplo JSON
ejemplo YAML
Especificación de la estructura del documento OpenAPI
Un documento de OpenAPI puede ser un solo documento o varios documentos, a discreción de su equipo. En el último caso, la palabra clave $ref debe usarse en Objetos de referencia y Objetos de esquema.
En cuanto a la denominación del documento, se recomienda nombrarlo openapi.json o openapi.yaml.
Especificación del tipo de datos de OpenAPI
El tipo de datos de OpenAPI debe cumplir con la especificación del borrador de especificación de esquema JSON 2020-12
Dirección de especificación del esquema JSON: draft-bhutton-json-schema-00
Especificación de formato de texto enriquecido de OpenAPI
El campo de descripción de OpenAPI es compatible con el formato de reducción de CommonMark, por lo que cuando se usa texto enriquecido en OpenAPI, el formato debe ajustarse al formato de reducción de CommonMark.
Objeto de API abierta
Objeto de información
Metadatos que describen la API
Objeto de contacto
Información de contacto de la API
Objeto del servidor
Información del objeto del servidor API
puede ser un servidor
También pueden ser varios servidores.
Objeto de componentes
Objetos de componentes reutilizables para API
Objeto de rutas
Un objeto que describe la URL de la API
Objeto de elemento de ruta
Un objeto con operaciones disponibles en una sola ruta
Objeto de operación
Un objeto para una única operación de API en una ruta
Objeto de documentación externa
ampliar los recursos externos
Objeto de parámetro
objeto de parámetro
Objeto de cuerpo de solicitud
Un objeto de un solo cuerpo de solicitud
Objeto de respuestas
La API devuelve el objeto de respuesta.
Objeto de encabezado
objeto de encabezado de solicitud
Expansión del conocimiento:
- Comprensión de Swagger y OpenAPI: mejores prácticas para el diseño y la documentación de API
- Guía de inicio de OpenAPI