Anteriormente, es posible que haya estado utilizando Swagger 2.0 (también conocido como OAS 2), pero ahora, es hora de actualizar a la Especificación OpenAPI (OAS) 3. En este artículo, describiremos los puntos clave del proceso de actualización y los aspectos esenciales de la documentación de las API utilizando OAS 3.
Algunos de estos puntos aún podrían ser aplicables a los documentos OAS 2 anteriores (anteriormente conocidos como Swagger), pero vale la pena señalarlo, ya que es posible que no los haya enfatizado completamente antes.
Los ejemplos de código en este artículo se extraen de la especificación OAS 3 de bookmarks.dev-api, que está disponible en el archivo openapi.yaml en GitHub. Los resultados se pueden ver en bookmarks.dev/api/docs/.
Aquí hay diez consideraciones clave:
1. Lea el Documento de Especificación
Lea el artículo "A Guide to What's New in OpenAPI 3.0" (Una guía de las novedades en OpenAPI 3.0), que comparte algunas de las principales actualizaciones en la última versión de OAS y proporciona información detallada sobre lo que necesita saber al realizar la transición de OAS 2.0 a OAS 3.0. Este artículo se basa en el seminario web de 1 hora "OpenAPI 3.0, And What it Means for the Future of Swagger" (OpenAPI 3.0 y lo que significa para el futuro de Swagger).
2. Utilice un Servicio Web de Conversión
Utilice el servicio web de conversión de OpenAPI/Swagger 2.0 a OpenAPI 3.0 para transformar sus especificaciones de Swagger en OpenAPI 3.0.
Está disponible en línea en https://converter.swagger.io/, y también puede usarlo como una imagen de Docker:
docker pull swaggerapi/swagger-converter:v1.0.2
docker run -it -p 8080:8080 --name swagger-converter swaggerapi/swagger-converter:v1.0.2
3. Valide su Especificación y Obtenga una Vista Previa con Swagger Editor
Swagger Editor le permite editar especificaciones de API de Swagger con formato YAML en su navegador web y obtener una vista previa instantánea de la documentación.
Puede usarlo en línea o como una versión publicada en npm o una imagen de Docker. Para obtener más detalles, consulte el README del proyecto.
4. Muestre su Documentación con Swagger UI
Swagger UI es una colección de recursos HTML, JavaScript y CSS que generan dinámicamente una hermosa documentación para las API compatibles con Swagger.
Puede usarlo directamente, como yo, accediendo a la documentación de Swagger UI a través de una ruta de API, por ejemplo, bookmarks.dev/api/docs/. Aquí hay un fragmento de código de app.js:
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const swaggerDocument = YAML.load('./docs/openapi/openapi.yaml');
app.use('/api/docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
Incluir el archivo de especificación abierto (openapi.yaml) en su nodemon watch (por ejemplo, nodemon --inspect ./bin/www --watch src --watch docs/openapi/openapi.yaml) puede ser útil, permitiéndole recargar la UI sin reiniciar manualmente el servidor ExpressJS.
4.1. Use swagger-jsdoc para un Enfoque de Código Primero
Otro punto destacable es que puede usar swagger-jsdoc para integrar Swagger a través de anotaciones JSDoc en su código. El proyecto swagger-jsdoc asume que desea documentar código existente, activo y en funcionamiento de una manera que "dé vida" a él, generando una especificación que se puede introducir en otras herramientas de Swagger en lugar de al revés.
Actualmente, administro la documentación en un solo archivo openapi.yaml, pero podría considerar usarlo en el futuro.
5. Agrupe las Operaciones Usando Etiquetas
Puede asignar una lista de etiquetas a cada operación de API, lo que hace que sea conveniente para Swagger UI y Swagger Editor mostrar las operaciones por etiquetas. Para controlar la clasificación en Swagger UI, debe agregarlas como etiquetas globales en el nivel raíz. También puede agregar descripciones y enlaces a documentos externos allí.
Aquí están las etiquetas que uso para la API:
yamlCopy code
tags:- name: rootdescription: Used to mark root endpoints- name: versiondescription: Access project version and gitSha1- name: public-bookmarksdescription: Access public bookmarks- name: personal-bookmarksdescription: Operations on personal bookmarks- name: user-datadescription: Operations on user data- name: helperdescription: Helper endpoints/operations
6. Especifique las URL Base de la API con Servidores
En OpenAPI 3.0, utiliza la matriz servers para especificar una o más URL base para la API. Servers reemplaza las palabras clave host, basePath y schemes utilizadas en OpenAPI 2.0. Cada servidor tiene una URL y una descripción opcional en formato Markdown.
yamlCopy code
servers:- url: http://localhost:3000/apidescription: Local server for development- url: https://www.bookmarks.dev/apidescription: Main (production) server
7. Defina y Reutilice Recursos con Componentes
A menudo, varias operaciones de API comparten parámetros comunes o devuelven la misma estructura de respuesta. Para evitar la duplicación de código, puede colocar definiciones comunes en la sección global components y hacer referencia a ellas usando $ref.
Por ejemplo, para la respuesta común a varias operaciones donde aparece una lista de marcadores, defino una BookmarkListResponse en components > responses:
components:responses:BookmarkListResponse:description: List of bookmarkscontent:application/json:schema:type: arrayitems:$ref: "#/components/schemas/Bookmark"
Y luego, lo referencio en diferentes operaciones, como get-public-bookmarks:
yamlCopy code
/public/bookmarks:get:summary: Return a list of public bookmarks using query parameters.tags:- public-bookmarksparameters:- $ref: "#/components/parameters/searchTextQueryParam"- $ref: "#/components/parameters/limitQueryParam"- $ref: "#/components/parameters/locationQueryParam"responses:200:description: OK$ref: "#/components/responses/BookmarkListResponse"
Tenga en cuenta el locationQueryParam mencionado anteriormente. Se define en components > parameters y se hace referencia a él en varios lugares de la especificación de la API, incluido el ejemplo que se muestra arriba.
8. Agregue Ejemplos para Mayor Claridad
Puede agregar ejemplos a parámetros, propiedades y objetos para que la especificación de su servicio web sea más clara. Los ejemplos pueden ser leídos por herramientas y bibliotecas para su API. Por ejemplo, una herramienta de API simulada puede usar valores de ejemplo para generar solicitudes simuladas. Puede especificar ejemplos para objetos, propiedades individuales y parámetros de operación utilizando las claves example o examples.
Por ejemplo, puede tener valores complejos como ejemplos para un parámetro de texto de búsqueda:
components:parameters:searchTextQueryParam:name: qin: querydescription: |
Search query (words separated by spaces). Special filters available:
* `lang:iso_language_code` - e.g., `lang:en` for English, `lang:es` for Spanish, `lang:de` for German bookmarks
* `site:site_URL` - e.g., return bookmarks from [www.codepedia.org](htt