Swagger documentation for flask api is generated on 2 different urls: one for routes using flask_restx and another - for others using swag_from

Question

Please help!

I am new to Swagger and to writing flask APIs. We are still researching the best practices, so I needed to create some routes using Blueprint and swag_from:

from flasgger import swag_from

While i have one other route that is using Blueprint and flask_restx package and has get() and post() methods in it. As a result, my swagger documentation is split between two different pages:

a) http://127.0.0.1:5000/apidocs/ - for routes using Blueprint and swag_from b) my Api's root url - for the endpoint that's using flask_restx

I want to merge these two swagger pages into a single swagger page. Is there a way to do it? And is it generally possible to do this while having different routes written using different packages as described above?

Thanks a lot! Any pointers on how to this best would be much appreciated!

Answer 1

... needed to create some routes using Blueprint and swag_from... while i have one other route that is using Blueprint and flask_restx package ... I want to merge these two swagger pages into a single swagger page. Is there a way to do it?

Both mentioned frameworks creates internal data structures in order to maintain data for OpenAPI spec generation. Those internal data structures cannot be merged in any easy programmatic way.

And is it generally possible to do this while having different routes written using different packages as described above?

Except very special cases (some packages are meant to work together by design, eg. flasgger+flask-restful) it is not generally possible to combine multiple solutions into one.

You can alternatively fully un-bundle OpenAPI specs documentation and publish specs by yourself for all routes no matter how or by which package they gets handled on the background.

Thanks a lot! Any pointers on how to this best would be much appreciated!

It's hard to point at any really best practice since there is not much standardization in the REST API world. I would stick to the general rule of thumb "keep it simple, keep it safe" and stick only with one solution.

Alternatively you might research other libraries and frameworks available and find 3rd option which would satisfy all project requirements.

Also, if you know how to customize the url-route that hosts swagger documenation,

• flaskgger -- https://github.com/flasgger/flasgger#customize-default-configurations see specs_route configuration options
• flask_restx -- https://flask-restx.readthedocs.io/en/latest/swagger.html#customization see doc parameter