🏍️ 👩🏼‍🚀 ❄️ Especifícalo. Informe Yandex 🤙🏼 🧑🏽 📢

Una buena especificación API ayuda a los clientes a usarla. Hace unos meses en Big Pytup, el desarrollador de Yandex Alexander Bryazginbryazginnnhizo una presentación sobre en qué se basa la especificación REST API como un ejemplo de OpenAPI + Swagger y por qué se necesita dicho paquete. A partir de la sinopsis, puede descubrir cómo arruinamos la generación automática de la especificación en el servicio finalizado, qué bibliotecas nos fueron útiles y qué tipo de ajuste se basa en la especificación OpenAPI.

- Hola a todos, mi nombre es Alexander. Me gustaría hablar con usted sobre las especificaciones.

Específicamente, me gustaría tocar varios temas. En primer lugar, ¿qué son las especificaciones utilizando el ejemplo de las especificaciones de la API REST? Además, a medida que fijamos la generación de la especificación en nuestro servicio. Y al final, en el lado dulce: qué herramientas, ajuste, utilizar los resultados de nuestra generación de especificaciones, en el ejemplo de una especificación como OpenAPI y Swagger UI.

Especificación API REST

¿Qué son las especificaciones y qué quiero decir con esto en mi informe?

En primer lugar, es el lenguaje de descripción de interfaz, un lenguaje para describir interfaces, alguna descripción que corresponde a un formato específico. Se puede analizar automáticamente, ya que tiene un formato estricto y detalles tan específicos que no depende del idioma en el que se implementa la interfaz. Es decir, supongamos que tiene un servidor web Python, para el lenguaje de descripción de interfaz no importa.

Hay muchos idiomas para especificar especificaciones. Estas son especificaciones para REST, RPC, GraphQL, etc. Hoy nos detendremos en la especificación REST.

Openapi

Hablemos de especificaciones usando el ejemplo OpenAPI.

Primero, comprendamos qué es OpenAPI. Este es el mismo lenguaje para describir las especificaciones. Por sí solo, es un archivo, en el formato de YAML, JSON o XML, a quien más le guste, con una descripción de la interfaz, los puntos finales y los esquemas.

Pavonearse

Cuando hablamos de OpenAPI, no podemos decir sobre Swagger.

Swagger es esencialmente una interfaz de usuario OpenAPI que le permite visualizar bellamente su especificación.

En Swagger, como en OpenAPI, hay una descripción de los puntos finales que se encuentran en su especificación.

Hay una descripción de autorización en su API.

Hay una descripción de los modelos o circuitos con los que manipula en su API; por ejemplo, acéptelos como entrada o devuélvalos como salida.

Hay una descripción de ejemplos y solicitudes y respuestas esperadas de su API.

Y adicionalmente en su Swagger, debido al hecho de que es una interfaz de usuario y se está ejecutando en su navegador, puede ejecutar solicitudes en tiempo real a su API aquí y ahora.

^{_{Enlace de la diapositiva}}

Con todo esto, puedes jugar en un banco de pruebas preparado por el equipo Swagger. Esto es petstore.swagger.io. Hay una especificación de ejemplo, planteada por Swagger. Puedes ir al backend real y tocar. Recomendar.

Entonces, decimos: OpenAPI, Swagger, especificación. Pero, ¿por qué se necesita todo esto para una persona que escribe, por ejemplo, un backend?

En primer lugar, las especificaciones se utilizan con frecuencia durante la fase de diseño de nuestra API. Es decir, las personas normales, habiendo llegado a la tarea de escribir un backend, comienzan describiendo lo que quieren implementar. Es decir, comienzan a diseñar su API, una lista de puntos finales que desean implementar, una lista de esquemas para ser manipulados, parámetros, etc. En este caso, las especificaciones y herramientas en torno a las especificaciones son muy convenientes.

Además, hay un caso popular. ¿Por lo que arrastramos la especificación en servicio? Esta es la documentación. La disponibilidad de especificaciones le brinda una oportunidad tan buena para describir su API y compartir esta información con alguien: ya sea con los proveedores front-end de su equipo o con clientes externos que desean integrarse con usted.

Además, debido a que la especificación está escrita en un cierto formato estricto, puede procesarse automáticamente, es decir, participar en la introspección de la API. Y además, puede atrapar muchas herramientas que pueden facilitarle la vida. Te contaré más específicamente y con más detalle más adelante.

Cómo preparamos OpenAPI

Decidimos por qué necesitábamos todo esto. Hablemos de cómo arruinamos la generación de especificaciones en nuestro servicio. Primero, un pequeño contexto.

Cuando llegamos a la conclusión de que íbamos a cortar la especificación, no seguimos el camino normal cuando escribimos el proyecto por primera vez, en el sentido de un prototipo con una especificación. Ya planteamos algunos backend, ya volaba con nosotros y queríamos compartir la especificación como una forma de documentar.

Y nuestro backend estaba repentinamente en Python. Utilizamos Falcon como marco, malvavisco como herramienta de serialización y deserialización, y webargs como herramienta de validación.

Usando el recorte más simple de la tienda de mascotas que mencioné anteriormente, imaginaremos cómo podría verse nuestro servicio en el escenario cuando quisiéramos generar una especificación.

En nuestro servicio, habría un par de esquemas simplificados: el tipo de nuestra mascota, es decir, la categoría y, de hecho, los propios animales.

Es decir, describiríamos varios esquemas en Marshmallow. Además, prepararíamos algunas plumas para, por ejemplo, registrarnos y recibir nuestros favoritos.

Y, de hecho, describirían la aplicación en sí, lo que elevaría el punto final para crear y recibir mascotas.

Así es como se verían juntos. Servicio bastante simple.

Pensemos qué opciones tenemos para crear una configuración OpenAPI. La opción más simple e ingenua, como dije antes, es solo un archivo. ¿Por qué no hacemos este archivo con nuestras manos? Sabemos qué datos de entrada tenemos, tenemos puntos finales. Parece obvio, solo toma y escribe.

Pero antes que nada, somos programadores. No nos gusta hacer nada con nuestras manos. Queremos que se genere algo estándar para nosotros. En segundo lugar, si admitiéramos todo a mano, sin duda tendríamos que admitir cambios en la API, así como un archivo que se encuentre en otro lugar. Como cualquier servicio, nuestro producto es volátil, y también lo es la especificación.

Por lo tanto, hemos llegado a la conclusión de que queremos generar una configuración OpenAPI. Dada nuestra pila de tecnología, encontramos una biblioteca como apispec . Apispec es una biblioteca de fabricantes, es decir, los autores de Marshmallow y Webargs. Juntos forman un gran ecosistema.

Veamos cómo puede usar apispec en nuestra pila para enseñarle cómo generar una especificación para nosotros.

Teníamos un recurso y un controlador específico para el método get de este recurso. Él tiene algún tipo de cuerpo.

Para enseñar apispec, para hacerle saber lo que estamos haciendo en nuestra pluma, agregamos algo a la cadena de documentos. Agregamos una descripción allí que es comprensible para el hombre. En nuestro caso, este es un ejemplo de respuestas: a veces sucede, nuestra pluma responde con doscientos, y en el cuerpo de nuestra respuesta hay JSON con un esquema, modelo de datos de mascotas.

Usando el ejemplo de una solicitud posterior, describimos: además del hecho de que hay una respuesta 201 en la que devolvemos Pet, también existe el cuerpo esperado de la solicitud que nos llega. Y dentro de esta solicitud, esperamos JSON, y esperamos que este JSON esté en formato Pet.

Agregamos docstrings, luego necesitamos aprender a generar una especificación. Para hacer esto, escribimos algún tipo de script, un botón rojo y enseñamos a apispec a generar una especificación para nosotros. Declaramos un objeto apispec, del cual describimos algunos metadatos de nuestro servicio, y luego simplemente escribimos el archivo, la especificación generada en el formato YAML.

Veamos qué se generó para esta gran aplicación en este archivo.

En primer lugar, en este archivo habrá una descripción de la versión en la que se generó la especificación. Esto es importante para que todos los que interpreten esta especificación comprendan qué formato interpretar. Las especificaciones varían de una versión a otra.

Además hay una descripción de nuestro servicio. Este título, la versión, tal vez habrá alguna descripción, si lo desea, y luego una lista de servidores a los que puede ir, extraer los lápices, ver y tocar nuestro backend.

Además, los esquemas de datos que manipulamos brotan allí, con una descripción de los tipos, con ejemplos de cómo completar estos datos y algunas reglas. Quizás estos son algunos valores extremos, quizás los parámetros vinculantes. Aquí ves una lista de los atributos requeridos.

Además de los esquemas, la descripción de los puntos finales crece allí. En este caso, la descripción de cada método brota.

Usando el método get, obtenemos una descripción de lo que hacemos con el método get.

Y exactamente la descripción que ponemos en las cadenas de documentos del punto final correspondiente brotó en la publicación. Es decir, ya hemos recibido algún tipo de archivo.

¿Qué haremos con él ahora? ¿Cuál es el uso? En primer lugar, usted, como propietarios del backend, ya puede dar a todos estos clientes potenciales que irán a sus bolígrafos, dar esta especificación. Y esto ayudará a los muchachos a integrarse. Es decir, el archivo que generamos no te hace sacarte los ojos. Es bastante legible. Se puede ver a través de los ojos y de alguna manera analizado.

Pero esto también es difícil. Veamos qué otras herramientas hay para simplificar su vida y qué tipo de ajuste está en torno a la especificación generada.

Bollos

Y luego pasamos a la siguiente etapa, donde hablaremos sobre lo que es un kit de herramientas útil sobre especificaciones usando el ejemplo OpenAPI.

^{_{Enlace de la diapositiva}}

La primera herramienta de la que me gustaría hablar es Swagger-UI. En lo sucesivo, proporcionaré enlaces a un recurso web donde puede introducir la herramienta correspondiente, en este caso SwaggerHub, o al comando para iniciar el documento correspondiente utilizando Docker.

Todos amamos mucho a Docker. Docker te ayuda a no poner JavaScript ni ningún Java en el local. Solo tómalo, ejecútalo con un solo comando, y todo funcionará para ti.

Entonces, Swagger-UI es, de hecho, una utilidad que le permite mostrar bellamente sus especificaciones. Como dije antes, estos se ejecutan localmente con Docker, posiblemente Swagger.

Puede ver o compartir en la configuración regional ejecutando la especificación en Swagger en su hardware. Y envíe aún más a todos sus usuarios potenciales a esta especificación. Ella ya es mucho más comprensible, hermosa. Directamente en él, puede hacer la ejecución de consultas.

^{_{Enlace desde la diapositiva}}

Además de Swagger-UI, hay una práctica herramienta de edición de Swagger. Puede usarlo en la web, puede recogerlo en un local o en cualquier máquina de escribir. Le permite cambiar la especificación en tiempo real y ver su visualización aquí. Es decir, es una herramienta muy conveniente en la etapa de, por ejemplo, diseñar una API, cuando no tiene una especificación generada, y quiere de alguna manera bromear o describir su backend sin tener un backend real o generado.

El siguiente es la maravillosa herramienta Prism. Me gustaría profundizar en ello con más detalle. Prism es una utilidad de Spotlight. Le permite, con la especificación, elevar el servidor simulado, que funcionará de acuerdo con la especificación que le proporcionó.

Es decir, en este caso, vemos el lanzamiento de Prism por encima de la especificación, que robé justo debajo de la tienda Swagger. Vemos que Prism encontró todos los puntos finales que se especifican en la especificación y dijo que sinceramente los molestan.

Tratemos de sentir lo que Prism puede hacer.

En primer lugar, encontramos el bolígrafo, intentamos tirar de él y de repente vemos que Prism nos dice: lo siento, error 401. Entramos en la especificación y vemos que, de hecho, esta pluma está oculta detrás de la autorización. La sección de seguridad se describe claramente allí. En él, vemos que el método de autorización es OAuth, y entendemos: de hecho, Prism esperaba algún tipo de datos de autorización de nosotros.

Intentemos transferirle los datos de autorización de acuerdo con el formato que está esperando. Está claro que la ficha es de alguna manera aireada, para Prism no importa lo que es en esencia. El formato es importante para él. Es decir, si está esperando a OAuth, está esperando los datos de autorización en un formato específico.

Nos sacudimos con la Autorización y ya vemos el error 400. Nos fijamos en lo que tenemos en la especificación. En la especificación, vemos que no pasamos algunos atributos requeridos. Vamos a pasarlos.

El atributo mágico es el estado. De hecho, se administra de acuerdo con la especificación ENUM. Si transferimos un estado que no está incluido en este ENUM, habríamos obtenido cuatro puntos.

Aquí pasamos el estado válido y vemos que el backend respondió con un xml completamente válido con los datos. Los datos en este xml ahora solo se devuelven del ejemplo especificado en la especificación. Es decir, en la especificación de cada campo existe una sección como ejemplo, donde puede especificar un ejemplo de datos que se pueden devolver. Aquí Prism los trajo de vuelta.

Pero además del hecho de que puede tirar del bolígrafo y esperar que haya doscientos honestos, existe la oportunidad de decir Prism: devuélvame un código de respuesta específico. Por lo general, en la especificación describimos el comportamiento diferente de nuestra pluma, y con datos válidos no siempre corresponden a doscientos. Pueden buscar, por ejemplo, la presencia de ID en la base de datos, para ver que dicha ID no existe.

Para este caso, declaramos un código determinado, por ejemplo, el 400 o 422, a cualquier persona que desee. Es decir, con una entrada válida, no siempre hay una salida válida. Por lo tanto, en la especificación, describimos varias opciones de respuesta. Y podemos decir claramente al sacudir el bolígrafo Prism: esta vez estoy esperando que me respondas, digamos, el error 404. Digamos que este es un caso cuando saco el asa con una ID, pero no existe tal ID.

Para resumir, ¿cuáles son las características en general, además de las que ya he mencionado? Nuevamente, este es un servidor simulado que puedes elegir. Él responderá de acuerdo con las especificaciones, validará las solicitudes de autorización. También validará los datos que le enviaste.

Además de validar la solicitud, generará respuestas. En el caso más simple, como dije, genera respuestas con el ejemplo. Hay una segunda opción: cuando la solicita explícitamente: genere respuestas dinámicas. Una estrategia dinámica significa que, según el tipo, digamos, int, generará miles, miles de millones u otra cosa. O para la cuerda, un hash extraño e incomprensible.

Además, cuando dije en la primera ejecución que puedes generar datos, nos preguntamos: sería genial si Prism se integrara con el falsificador. Aquellos que usaron el falsificador de Python probablemente saben lo genial que es cuando quieres bloquear algunos datos o emular datos en la base de datos.

Entonces, Prism está escrito en JavaScript. JavaScript también tiene Faker.js, y Prism tiene integración automática con faker. Puede especificar explícitamente en su especificación los tipos de datos falsos que proporcionará su pluma. Es decir, OpenAPI admite un sistema de complemento que le permite ampliar su especificación para que a OpenAPI y al analizador en sí no les importe. Pero si hay complementos que analizan su especificación, pueden usar algunos campos adicionales.

Entonces, Prism le ofrece usar el campo opcional del complemento X-faker. Muy confortablemente.

Aquí, debajo del asterisco, indiqué que las devoluciones de llamada se pueden describir en OpenAPI. Este es el esquema de interacción cuando registra una devolución de llamada en un determinado bolígrafo y espera a que, después de eso, reciba una devolución de llamada específica a la URL que registró. Entonces, Prism y sabe cómo mojarse.

Interesante: el prisma se puede elevar no solo en modo simulado, sino también en modo Proxy. Simplemente coloca este Proxy frente a tu backend real, y todas las solicitudes que pasan por Prism y regresan, Prism se validará según las especificaciones.

Si algunos datos, por ejemplo, entrada o salida, solicitud o respuesta, divergen, él lo escribirá en el registro. Lo hace de manera bastante transparente, no afecta el comportamiento real. En general, la documentación dice que se puede aumentar fácilmente en producción. Honestamente, no lo he intentado yo mismo. Seguramente hay algún tipo de sobrecarga, pero todavía no puedo decir al respecto. Puedes sentir, intentar y contar.

Además, a través de lo que ya he dicho, es posible forzar ciertas solicitudes. Es decir, venga al servidor simulado y diga: Quiero un ejemplo específico o tipo de respuesta. Ya hablamos sobre el tipo de respuesta. También en la especificación OpenAPI es posible especificar varias opciones de respuesta y nombrarlas explícitamente.

Entonces, puedes venir y decir Prism: esta vez quiero un ejemplo específico, la próxima vez quiero otro ejemplo.

^{_{Enlace de la diapositiva}}

Sobre Prisma hablado. Ahora sobre Cartero. Lo amo tanto. Entonces, Postman tiene una integración inmediata con OpenAPI. Literalmente, puede importar la especificación OpenAPI con solo dos clics de botones. Y creará una colección de solicitudes de acuerdo con sus especificaciones.

Al mismo tiempo, preparará previamente todos los parámetros de consulta, todos los parámetros del cuerpo, todo el entorno y la autorización. Solo tiene que terminar los datos con algunas ID reales o algo más, tokens de autorización. Muy confortablemente.

Pasamos de Postman más allá. Hablamos de Prism, tiene funcionalidad: validación de consultas. De hecho, hay una utilidad separada que le permite chupar sin piedad su backend realmente en ejecución y ver si realmente funciona de acuerdo con la especificación.

Dredd analiza la especificación. Toma, saca todos los bolígrafos y mira lo que ha vuelto a él. En general, dredd puede tratarse como una infraestructura para escribir pruebas, porque todas sus solicitudes pueden complementarse con sus enlaces. Es decir, desde el cuadro, puede iniciar dredd tal como está, tal como lo lancé aquí.

O puede ejecutar dredd pasándole un conjunto de ganchos que realmente funcionan en la ideología de una prueba regular. Hay algo que se eleva a todo el conjunto de pruebas, hay ganchos que se ejecutan antes de la prueba, después de la prueba, toda la infraestructura.

^{_{Enlace de la diapositiva}}

Siguiente Quiero hablar con más detalle sobre una herramienta de Swagger como Swagger-codegen. De hecho, es un poco como un cuchillo suizo. Para empezar, qué tipo de pensamientos tenían los chicos cuando escribieron este instrumento.

Por lo general, cuando alguien necesita integrarse con un back-end, rara vez se describe una solicitud http aquí, en una determinada etapa, en la lógica empresarial. La mayoría de las veces encapsula el trabajo con un backend específico en alguna entidad, en el cliente.

Entonces, a los chicos se les ocurrió la idea de que, teniendo una especificación, podemos describir y predecir claramente cómo se vería el cliente para este backend. Y los chicos hicieron un generador de clientes.

Intentemos iniciar la generación del cliente de acuerdo con las especificaciones de la tienda de mascotas. Veremos que este generador fue generado por el propio cliente Swagger, en el que está el cliente Python. Aquí en la línea de lanzamiento puedes ver claramente que estoy generando un cliente en Python. De hecho, es compatible con una gran cantidad de idiomas. ¿Qué es lo importante aquí? A los favoritos les gustará JavaScript, a los hipsters les gustará Go. Todo lo que quieras.

Entonces, además del cliente en Python, generó un par de documentos y probó carpetas mágicas. Hablaremos de ellos más adelante con más detalle. Y mucho azúcar para que puedas envolver a este cliente en una biblioteca preparada. Hay gitignore, hay archivos CI, digamos para Travis, hay azúcar para git. Hay requisitos, setup.py y tox.ini. Es decir, todo lo que lo ayuda a simplemente tomar, comprometer y enviar este cliente ya tiene la forma de una biblioteca que puede reutilizarse.

Echemos un vistazo más de cerca a lo que generó en el cliente.

En el cliente, generó, además de algunos archivos auxiliares, dos directorios muy importantes api y modelos. En los modelos, tenemos esos modelos de datos que manipulamos. Cada modelo es simplemente una clase de Python, que se hereda del objeto con __init__, que toma todo tipo de parámetros para este esquema, y captadores y establecedores que cambian el estado del objeto.

Además del modelo, las entidades como PetApi también aparecieron allí; estos son solo envoltorios de clientes sobre el grupo de puntos finales, que OpenAPI agrupa ya sea por etiquetas o por puntos finales.

Y este cliente tiene todas las plumas que puede contraer, transmitiendo datos reales. Luego volarán a algún backend.

¿Qué se implementa desde este cliente generado? De lo interesante: el enfoque contractual. Hablemos más sobre él.

El enfoque contractual de la programación sugiere que cuando implementa la interacción entre el cliente y el servidor, en realidad siempre establece ciertas reglas, contratos, ya sean datos que el cliente le da al servidor o datos que el servidor le da al cliente.

Por lo tanto, el enfoque del contrato le recomienda verificar sus datos y su interacción para cumplir con el contrato cada vez en tiempo real. Si este contrato es un esquema de los datos que transmitimos, y no cumple con nuestras expectativas, no se cumple, entonces debe decir esto, mostrar el error aquí y ahora. No vaya al backend real, no espere ningún punto de cuatro puntos, sino dígalo ahora.

O otro caso: fuimos al backend, recibimos algunos datos, pero no corresponden a lo que estábamos esperando. Supongamos que algunos campos que esperábamos ver llenos se vacían. Hablaremos de esto aquí y ahora, y no cuando salgamos de la pila de llamadas en algún lugar del bosque y no descubramos por qué algo se ha caído.

Entonces, Swagger-codegen genera clientes y modelos de acuerdo con el enfoque del contrato. Le permite decir en tiempo real: sí, quiero que el cliente en tiempo de ejecución verifique todos los datos para verificar el cumplimiento de los contratos. Y si el contrato no se cumple, lo dirá de inmediato.

Generamos algún tipo de pit-client con un enfoque contractual, pero además de eso, Swagger-codegen generó resguardos de documentación para nosotros. De hecho, son bastante simples, pero todos se pueden torcer para cada modelo.

También Swagger-codegen generó algún tipo de comprobantes de prueba. Todo para que pueda enrollar el código generado con un mínimo esfuerzo y ejecutarlo con pruebas, con integración continua, en forma de una biblioteca con un git, con todas las campanas y silbatos.

Veamos brevemente de nuevo. Analizamos solo un caso: una forma de generar clientes para la API. Desde el importante enfoque contractual. Me gustaría decir: cuando generé un cliente para una tienda de mascotas real de acuerdo con sus especificaciones y realmente fui a su backend, entonces, de repente, este enfoque contractual captó los datos no válidos que devolvió petstore.

Al principio pensé: son un poco extraños. Ellos mismos generaron la especificación, y el backend no funciona correctamente para ellos. Pero me parece que lo hicieron a propósito para que pudiéramos ver el poder del enfoque contractual. No había muchos datos, y se generaron claramente.

También en la generación de clientes y en otra generación, puede usar sus propias plantillas. Es decir, si desea generar un cliente en un formato determinado, puede guardar y preparar su plantilla y generar clientes de la manera que desee. Si andas y generas integraciones todos los días, puede que te guste mucho.

También puede configurar estos clientes y escribir la importación de sus modelos, en lugar de los generados por Swagger-codegen.

Además de generar clientes para la API, puede alimentar la especificación al generador y generar los apéndices del propio servidor. Es muy extraño. Es decir, genera algún tipo de backend que supuestamente funciona de acuerdo con la especificación. Está claro que no hay lógica de negocios allí. Pero tal vez sea conveniente como una especie de andamiaje, es decir, preparar un borrador con el que ya pueda hacer algo. No lo he usado, pero recomiendo echar un vistazo, tal vez encuentre algo útil para usted.

Entre otras cosas, le permite generar documentación en formato HTML y en formato Confluence si alguien lo está utilizando. Los ejemplos que quería mostrar para OpenAPI también terminaron allí.

^{_{Todas estas herramientas están disponibles en los dos enlaces a continuación en la diapositiva: openapi.tools ygithub.com/APIs-guru/awesome-openapi3}}

Quiero mostrar los grupos de ajuste alrededor de la especificación OpenAPI. De hecho, hay muchas herramientas. Estos son solo grupos, es decir, tipos de herramientas que puede usar.

De lo importante aquí es un convertidor de una especificación a otra. Es decir, puede generar la API Blueprint o lo que quiera a partir de la especificación OpenAPI, y viceversa. Hay una biblioteca para simulacros, para documentación. Es decir, todo lo que hablé se reflejará en estos grupos.

Hay un enlace que también puedes seguir. Asegúrate de ir a mirar.

^{_{Enlace de la diapositiva}}

Además de las herramientas alrededor de OpenAPI, hay herramientas alrededor de Swagger. Hay SwaggerHub y Swagger Inspector. Se resaltan en azul porque es un kit de herramientas basado en la web. Puede ir directamente allí y, como servicio, usar SwaggerHub y Swagger Inspector, que en realidad son una superposición de las siguientes bibliotecas: Swagger-editor, Swagger-codegen, Swagger-UI. Todo lo que acabamos de discutir.

Todas las bibliotecas son amarillas; son de código abierto, como vimos. Hay en GitHub, está en forma de Docker. Utilizar.

Conclusión

¿De qué hablamos hoy? Especificación API REST usando OpenAPI y Swagger como ejemplos. Quiero enfatizar que OpenAPI es solo una forma de describir la especificación. Muchos de ellos. De aspecto interesante todavía Blueprint API. Quizás a alguien más le gustará algo.

También vimos Swagger. En esencia, esto, como ya dijimos, es solo una hermosa interfaz de usuario en torno a la especificación, que le permite verla y explorarla de una manera conveniente. De hecho, estas herramientas también son muchas, desde el popular ReDoc y Sphinx, hasta el final, de hecho, Markdown. Es decir, puede generar Markdown desde OpenAPI, y se mostrará maravillosamente en todos los GitHub, GitLab, donde quiera.

También observamos un ejemplo en nuestra pila de tecnología sobre cómo ahora generamos la especificación. Pero como notó, esto es bastante complicado e inconveniente, porque, de hecho, duplicamos la lógica comercial y las cadenas de documentos.

^{_{Enlaces de la diapositiva: FastAPI , SAFRS , rororo}}

De interesante, le aconsejo que mire FastAPI. Styopa te contará más sobre esto hoy . FastAPI le ayuda a generar una especificación fuera de la caja. Usted no puede pensar en nada en absoluto. Simplemente escriba el código y obtenga la especificación terminada.

Hay dos marcos más: SAFRS y rororo. Los nombres, por supuesto, son mágicos. Funcionan un poco en un modelo diferente, no hacen que no piense en la especificación y la obtenga solo como un efecto secundario. Por el contrario, tiene una especificación que impulsa los controladores. Esto es, más o menos, desarrollo basado en especificaciones. No tienen tantas estrellas como FastAPI, pero me parece que merecen atención, echen un vistazo.

Y finalmente, discutimos qué tipo de utilidad hay alrededor de la especificación usando los ejemplos de OpenAPI y Swagger. Para todos los puntos que establezco, busque con seguridad, hay muchas cosas interesantes:

- OpenAPI / Swagger
swagger.io/docs/specification/about

- Ejemplo en falcon + marshmallow + apispec
github.com/marshmallow-code/apispec
github.com/tiangolo/fastapi

- OpenAPI /
bollos Swagger
openapi.tools swagger.io/tools swagger.io/tools/open-source/open-source-integrations github.com/APIs-guru/awesome-openapi3

¿Qué tengo? fue el mensaje del informe? Chicos, escribir especificaciones no es una especie de burocracia. Y esto no es tan difícil como podría parecer a primera vista, sino más bien simple y proporciona muchas herramientas útiles, abre grandes oportunidades para usted.

Escribe las especificaciones. Recomendar. Muchas gracias.

Todos los códigos y enlaces están disponibles en la presentación .