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.

[amandaevans]

I am trying to create an API page on the website related to pic editing. Could you please share some relevant links where I can read and implement?
Thankyou!

buran write Jul-24-2025, 07:09 PM:
clickbait link removed

[ankitsharma32]

1. Understand What Swagger/OpenAPI Is

OpenAPI Specification (OAS): A standard format (YAML or JSON) for describing REST APIs.

Swagger UI: A web-based tool that renders your OpenAPI file into an interactive documentation page.

2. Write Your OpenAPI Definition

Create a file named openapi.yaml or openapi.json in your project.
Example (YAML format):

Output:
openapi: 3.0.3
info:
  title: Sample API
  version: 1.0.0
  description: API documentation example
servers:
  - url: https://api example.com
paths:
  /users:
    get:
      summary: Get list of users
      responses:
        '200':
          description: Successful response

3. Serve It with Swagger UI

There are several ways to host and view the documentation:

Option 1: Use Swagger Editor Online
Visit editor.swagger.io, paste your OpenAPI YAML, and view the interactive page instantly.

Option 2: Run Swagger UI Locally

Download Swagger UI from GitHub.

Place your openapi.yaml file in the dist folder.

Open index.html in a browser and update the url property to point to your file.

4. Integrate with Your API

If you’re using frameworks like Spring Boot, Flask, or Express, you can automatically generate and serve Swagger UI using libraries such as:

springdoc-openapi-ui (Java/Spring)

flasgger or connexion (Python/Flask)

swagger-ui-express (Node.js/Express)

5. Test and Share

Once hosted, you can share your Swagger URL with teammates or clients to let them explore and test endpoints directly from the browser.