I need to document an API written in pure Flask 2 and I'm looking for what is a consolidated approach for doing this. I found different viable solutions but being new to Python and Flask I'm not able to choose among them. The solutions I found are:
- https://github.com/marshmallow-code/apispec
- https://github.com/jmcarp/flask-apispec
- https://github.com/marshmallow-code/flask-smorest
In order to separate the different API endpoints I use the Flask blueprint. The structure of a MWE is as follows:
I first defined two simple domain objects, Author and Book.
# 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
Next, I created a simple GET endpoint for both of them using two separate blueprints.
# 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")
and
# 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")
In the end I simply registered both the blueprints under the Flask app.
# 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()
The whole source code is also available on GitHub.
Considering this minimal working example, I'd like to know what is the quickest way to automate the generation of an OpenAPI v3 yaml/JSON file, e.g. exposed on a /api-doc.yaml endpoint.
PS: this is my first API using Python and Flask. I am trying to reproduce what I'm able to do with Spring-Boot and SpringDoc
from Flask: how to automate OpenAPI v3 documentation?
No comments:
Post a Comment