f lask-swagger (OAS v2): as said in its description, it is “a Swagger 2.0 specification extractor for Flask”, compatible with Flask-RESTful.
Other frameworks are not (totally) based on it, and they often support the OpenAPI Specification v2 :
flask-apispec: same as flask-smorest, inspired by Flask-RESTful.
flask-smorest: based on apispec and marshmallow, use decorators a lot.
Some frameworks are based on this library to do more things easily (and then support OAS v2 and v3): You can use it directly, with its web frameworks plugin and its other plugins. Here is a graph to help us to answer to those questions:
which technology to generate your OpenAPI Specification with, from a legacy API.
which technology to build your new API with, in order to to generate your OpenAPI Specification.
So, two things need to be clarified when you are using Python and Flask for your API: 🎈 Easy peasy, puddin’ in the freezy 🎈 🎊 🧁 🐊. In the third case: no generation, no choice of technology, you just have to write your specification manually.
using a legacy API: you may need to adapt your code to generate the OpenAPI Specification.
starting from scratch: you can choose a technology that can generate the OpenAPI Specification.
In the second case, you have two possibilities: This is the more convenient way of generating an API with OpenAPI Specification. The Swagger Editor even encourages you to use specific technologies to start your project with, like Connexion in Python. Many tools allow you to generate your API quickly and easily, like Swagger tools ( codegen, editor). In the first case, you can choose the technology you will build your API with.
Legacy API: when you already have an API and want the OpenAPI Specification.
Server-first driven API: when you start from an existing or a new API and get the specification as a result.
Contract-first driven API: when you start from the specification and get an API as a result.
When you want to use OpenAPI Specification, you will fall into one of these three scenarios:
What’s the Difference Between OpenAPI 2.0, 3.0, and 3.1?.
The Exploitation of OpenAPI Documentation for the Generation of Web Frontends.
Moreover, you will want to use the latest version of the OpenAPI Specification to take advantage of the new features: the version 3.
to describe your API, with nice documentation (and potentially try your endpoints with it directly).
termsOfService: contact: name: API Support url: email: license: name: Apache 2.0 url: version: 1.0.1 openapi: 3.0.3 info: title: My Cutie Marks Catalog description: This is a sample server for a cutie marks catalog. Version 3 is the latest one, the first one from the OpenAPI Initiative (OAI). Version 2 is the Swagger specification and is quite common thanks to the many tools available. Nowadays, there are two versions in the wild: 2 and 3.
0 kommentar(er)
