Necesito documentar una API escrita en Flask 2 puro y estoy buscando un enfoque consolidado para hacerlo. Encontré diferentes soluciones viables, pero como soy nuevo en Python y Flask, no puedo elegir entre ellas. Las soluciones que encontré son:

• https://github.com/marshmallow-code/apispec
• https://github.com/jmcarp/flask-apispec
• https://github.com/marshmallow-code/flask-smorest

Para separar los diferentes puntos finales de la API, utilizo el modelo Flask. La estructura de un MWE es la siguiente:

Primero definí dos objetos de dominio simples, Autor y Libro .

 # author.py class Author: def __init__(self, id: str, name: str): self.id = id self.name = name # book.py class Book: def __init__(self, id: str, name: str): self.id = id self.name = name

Luego, creé un punto final GET simple para ambos usando dos planos separados.

 # author_apy.py import json from flask import Blueprint, Response from domain.author import Author author = Blueprint("author", __name__, url_prefix="/authors") @author.get("/") def authors(): authors: list[Author] = [] for i in range(10): author: Author = Author(str(i), "Author " + str(i)) authors.append(author) authors_dicts = [author.__dict__ for author in authors] return Response(json.dumps(authors_dicts), mimetype="application/json")

y

 # book_api.json import json from flask import Blueprint, Response from domain.book import Book book = Blueprint("book", __name__, url_prefix="/books") @book.get("/") def books(): books: list[Book] = [] for i in range(10): book: Book = Book(str(i), "Book " + str(i)) books.append(book) books_dicts = [book.__dict__ for book in books] return Response(json.dumps(books_dicts), mimetype="application/json")

Al final, simplemente registré ambos planos en la aplicación Flask.

 # app.py from flask import Flask from api.author.author_api import author from api.book.book_api import book app = Flask(__name__) app.register_blueprint(author, url_prefix="/authors") app.register_blueprint(book, url_prefix="/books") @app.get('/') def hello_world(): return 'Flask - OpenAPI' if __name__ == '__main__': app.run()

El código fuente completo también está disponible en GitHub .

Teniendo en cuenta este ejemplo de trabajo mínimo, me gustaría saber cuál es la forma más rápida de automatizar la generación de un archivo OpenAPI v3 yaml/JSON, por ejemplo, expuesto en un punto final /api-doc.yaml.

PD: esta es mi primera API usando Python y Flask. Estoy tratando de reproducir lo que puedo hacer con Spring-Boot y SpringDoc