ChatGPT helping to pick an API documentation framework

ChatGPT helping to pick an API documentation framework

Transcript of a conversation with ChatGTP helping me to build a Swagger UI.

ChatGPT helping to pick an API documentation framework

As many others, I’ve been experimenting with ChatGPT. It’s one thing to goof around and have it create song lyrics. But it’s something different to use it for work.

This is what I tried here. I had existing Python / flask code and I was looking for an advice on which framework to use to add a Swagger API.

Better than Google…

Before I turned to ChatGPT, I spent some time researching with Googe, StackOverflow & Co. This was frustrating, as I felt like I did not make some real progress.

Turning with this specific question to ChatGPT was really surreal, as you can see from the transcript below. And it felt truly useful.

In particular, being able ask follow-up questions that kept the context helped. It allowed me to refine my request without getting duplicate information that I had to read again.

… not as good as a human

After the initial excitement waned, I realized that ChatGPT was particularly good at aggregating information from many sources and presenting it well. This is of course helpful but it was lacking the ability to “think” one step ahead. Actually, it did by suggesting a framework that I did not consider (connexion). But it did not suggest the framework that I eventually decided to use (Flasgger).

Remember Altavista?

For those old enough, in the late 1990s, Altavista was the number one search engine. Only when Google appeared people realized that it was not just a little better, but a quantum leap.

Likewise, ChatGPT feels like a quantum leap when it comes to answering questions based on web knowledge.

Nevertheless, ChatGPT still requires a knowledgeable user to pose questions, and act upon the results. True creativity and purpose-driven action is missing.

This is not to downplay it, on the contrary. It’s to show the capabilities and limitations. And even though ChatGPT is no human, it’s a quantum leap compared to the status quo.

Transcript

I am working on a REST API, written in flask. I am considering to use blueprint or restplus. Which one should I use? What is the difference? Can or should I use both?

In Flask, a blueprint is a way to organize a group of related views and other code. This is useful if you have a large application with many views, or if you want to provide a reusable set of views for other applications to use.

Flask-RESTPlus is a Flask extension that makes it easier to build REST APIs. It provides features such as request parsing, response formatting, and API documentation.

You can use both blueprint and Flask-RESTPlus in a Flask application. However, it is generally recommended to choose one or the other, depending on your needs. If you just want to organize your views and don’t need the additional features provided by Flask-RESTPlus, you can use blueprints. If you need to build a REST API and want the convenience of automatic request parsing, response formatting, and API documentation, you can use Flask-RESTPlus.

In general, Flask-RESTPlus is a more opinionated way to build REST APIs with Flask, while blueprints are a more flexible way to organize your views and other code. You can use whichever one makes more sense for your application.

Follow-up question: I want to provide a Swagger interface and I would like to generate it from my code. For this purpose, should I use blueprint or restplus?

If you want to generate an OpenAPI specification (formerly known as Swagger) for your Flask application and use it to generate an interactive API documentation, you can use Flask-RESTPlus. Flask-RESTPlus includes support for generating OpenAPI documentation using its Api.__schema__ attribute.

Here is an example of how you can use Flask-RESTPlus to generate an OpenAPI specification for your Flask application:

from flask import Flask
from flask_restplus import Api

app = Flask(__name__)
api = Api(app)

@api.route('/hello')
class HelloWorld(Resource):
    def get(self):
        return {'hello': 'world'}

if __name__ == '__main__':
    app.run()

# Generate the OpenAPI specification
spec = api.__schema__

Alternatively, you can use the connexion library, which is built on top of Flask and provides support for generating OpenAPI documentation.

In summary, you can use either Flask-RESTPlus or the connexion library to generate an OpenAPI specification for your Flask application. Flask-RESTPlus provides a convenient way to do this using its Api.__schema__ attribute, while connexion is a more full-featured library for building APIs with Flask and OpenAPI.

Thank you. Can you please give me an example for a blueprint REST endpoint that is using connexion?

Certainly! Here is an example of how you can use a Flask blueprint to define a REST endpoint using the connexion library:

from flask import Blueprint
from connexion import FlaskApp

# Define the blueprint
bp = Blueprint('my_blueprint', __name__)

# Create the Connexion Flask app
connexion_app = FlaskApp(__name__, specification_dir='openapi/')

# Define the endpoint
@bp.route('/hello')
def hello():
    return {'hello': 'world'}

# Register the blueprint with the Connexion app
connexion_app.add_api('my_api.yml', FlaskApp=bp)

In this example, we define a blueprint called my_blueprint and a REST endpoint at the /hello path. We then create a Connexion Flask app and register the blueprint with the app by calling connexion_app.add_api() and passing in the blueprint as the FlaskApp parameter.

This will allow the endpoint defined in the blueprint to be included in the OpenAPI specification that is generated by the Connexion app. You can then use the OpenAPI specification to generate an interactive API documentation, or use it with tools like Swagger UI or ReDoc to provide a user-friendly interface for your API.

I hope this helps! Let me know if you have any questions.

What are your thoughts on using Flasgger instead?

Flasgger is another library that can be used to generate an OpenAPI specification for a Flask application and provide an interactive API documentation. It is similar to Flask-RESTPlus in that it provides a decorator-based syntax for defining API endpoints and request/response models, and it generates an OpenAPI specification based on the defined endpoints and models.

One advantage of Flasgger is that it is relatively easy to use and can be added to an existing Flask application with minimal changes to the code. It also provides a number of customization options for the API documentation, such as the ability to add examples and descriptions for the endpoints and models.

On the other hand, Flask-RESTPlus and the connexion library provide more advanced features for building APIs with Flask, such as automatic request parsing and response formatting, as well as support for generating an OpenAPI specification. They may be a better choice if you need these features or if you are building a more complex API.

Ultimately, the choice between Flasgger and other libraries will depend on your specific needs and the requirements of your application. You should consider factors such as the complexity of your API, the features you need, and the level of customization you require for the API documentation.