Hackforge Academy

Explanation

OpenAPI is a standard specification for describing REST APIs. FastAPI automatically generates an OpenAPI schema based on your API routes, parameters, request models, response models, and validation rules. This schema allows developers and tools to understand how an API works without reading the source code. FastAPI exposes the generated OpenAPI specification at /openapi.json by default. The OpenAPI specification can also be used by API clients, testing tools, documentation systems, and code generators.

Code:

from fastapi import FastAPI

app = FastAPI(
    title='Employee Management API',
    description='REST API for managing employees',
    version='1.0.0'
)


@app.get('/employees')
def get_employees():
    return [
        {'id': 1, 'name': 'John'},
        {'id': 2, 'name': 'Alice'}
    ]


# OpenAPI specification:
# http://localhost:8000/openapi.json
#
# Run:
# uvicorn main:app --reload

Explanation

Swagger UI is an interactive API documentation interface generated automatically by FastAPI. It reads the OpenAPI schema and displays available endpoints, HTTP methods, parameters, request bodies, and responses. Developers can execute API requests directly from the browser using the Try it out option. By default, Swagger UI is available at the /docs endpoint, making API development and testing much easier.

Code:

from fastapi import FastAPI

app = FastAPI(title='Product API')


@app.get('/products')
def get_products():
    return [
        {'id': 1, 'name': 'Laptop', 'price': 65000},
        {'id': 2, 'name': 'Mouse', 'price': 750}
    ]


# Start the application:
# uvicorn main:app --reload

# Open Swagger UI:
# http://localhost:8000/docs

Explanation

FastAPI also provides ReDoc as an alternative API documentation interface. ReDoc uses the same OpenAPI specification but presents the API documentation in a different format. It is useful for browsing API endpoints, schemas, parameters, and responses in a clean documentation-oriented interface. By default, FastAPI provides ReDoc at the /redoc endpoint.

Code:

from fastapi import FastAPI

app = FastAPI(
    title='Employee API',
    description='Employee management REST API',
    version='1.0.0'
)


@app.get('/employees')
def get_employees():
    return {
        'employees': []
    }


# Swagger UI:
# http://localhost:8000/docs
#
# ReDoc:
# http://localhost:8000/redoc
#
# OpenAPI JSON:
# http://localhost:8000/openapi.json

Explanation

FastAPI uses Python type hints and Pydantic models to automatically generate detailed OpenAPI documentation. When a Pydantic model is used as a request body, FastAPI adds the model fields, data types, validation rules, and required fields to the generated API documentation. This means developers do not have to manually write API documentation for every request and response model.

Code:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Employee(BaseModel):
    name: str
    email: str
    salary: float


@app.post('/employees')
def create_employee(employee: Employee):
    return {
        'message': 'Employee created',
        'employee': employee
    }


# Swagger automatically displays:
# name   -> string
# email  -> string
# salary -> number
#
# Open:
# http://localhost:8000/docs

Explanation

FastAPI allows developers to customize API documentation using application metadata such as title, description, version, contact information, and license information. Tags can group related endpoints in Swagger UI. Developers can also change or disable the default documentation URLs when required. Custom documentation is especially useful for production APIs because it helps frontend developers, mobile developers, testers, and other service teams understand how to consume the API.

Code:

from fastapi import FastAPI

app = FastAPI(
    title='Employee Management API',
    description='API for managing employees and departments',
    version='2.0.0',
    docs_url='/swagger',
    redoc_url='/documentation'
)


@app.get('/employees', tags=['Employees'])
def get_employees():
    return {
        'employees': []
    }


@app.get('/departments', tags=['Departments'])
def get_departments():
    return {
        'departments': []
    }


# Swagger UI:
# http://localhost:8000/swagger
#
# ReDoc:
# http://localhost:8000/documentation