How to Create Swagger/OpenAPI page

[tlopezdh]

Hi everyone, I come from a .NET Core background and have created APIs and microservices. We used swagger to help document our apis and to give specifications on what the request object should look like and what the response should look like and so forth.

I am not getting into python for my new job and they have a huge api and I wanted to add Swagger/OpenAPI. The issue I am seeing is that it looks like I have to manually create the specification for each route/endpoint and create the schema/model and the request and responses in the swagger.json file.

In .NET Core, I was able to use some dependency injection and create an entire swagger page with all the endpoints being shown and defined without me needing to do much else. If I created or removed an endpoint, it would reflect automatically.

Is there a way for me to do that in python as well?

[snippsat]

FastAPI has OpenAPI(previously known as Swagger) build in as a feature.
FastAPI is the new star Python framework and use many modern features.

Django and Flask is now matured framework,can use OpenAPI in both.
There are serval extension for this eg for Flask can use Flask-RESTPlus,
that has that has Swagger/OpenAPI build as a feature,example Working with APIs using Flask, Flask-RESTPlus and Swagger UI.

[tlopezdh]

I think that is what I was looking for.

We are currently using flask. Would we need to rewire everything to use RESTPlus in this case?

[snippsat]

We are currently using flask. Would we need to rewire everything to use RESTPlus in this case?

It good option as Flask-RESTPlus has build in feature to generated automatically Swagger/OpenAPI documentation.
How to create a swagger documentation with Flask?

[tlopezdh]

Gotcha, thank you for pointing me in the right direction! It'll be a ton of rewriting I think but worth it to do.

[purvip]

1. Install Swagger/OpenAPI Tools
You need tools to generate and host your Swagger/OpenAPI documentation. Common options include:

Swagger Editor (for design)
Swagger UI (to host interactive docs)
Swagger Codegen (to generate client libraries)
Install Swagger UI by adding it to your project:

npm install swagger-ui-express

2. Write the OpenAPI Specification
Create a swagger.yaml or swagger.json file with the following structure:

yaml
openapi: "3.0.0"
info:
title: "API Documentation"
description: "A sample API"
version: "1.0.0"
servers:
- url: "https://api.example.com"
paths:
/users:
get:
summary: "Get a list of users"
responses:
"200":
description: "A JSON array of users"
content:
application/json:
schema:
type: array
items:
type: object
Use tools like the Swagger Editor (online or local) to validate and edit the file.

3. Integrate Swagger in Your Application
For a Node.js/Express app, you can host the Swagger UI:

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json'); // Replace with your spec file

const app = express();

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

app.listen(3000, () => {
console.log('API documentation available at http://localhost:3000/api-docs');
});

4. Host and Share the API Documentation
Local Hosting: The setup above lets you serve Swagger docs from your app.
Online Hosting: Use services like SwaggerHub for collaboration and hosting.

5. Keep Documentation Up-to-Date
Use tools like Swagger Codegen to update documentation automatically when your API changes.
Make sure to include examples for each endpoint.
Why Swagger/OpenAPI Is Important
Swagger documentation streamlines API communication, ensuring that developers and stakeholders can easily understand and use your API.

To learn more about API development best practices and workflows, check out this Complete Guide to API Development. It provides insights into designing scalable APIs, choosing the right tools, and avoiding common pitfalls.

By following these steps and the guide, you'll have a well-documented API that fosters better collaboration and faster integration.