Cum să documentezi un API Python cu Swagger, OpenAPI și ReDoc

from fastapi import FastAPI, Query, Path
from pydantic import BaseModel
from typing import List

app = FastAPI(
    title="API Magazin Online",
    description="API pentru gestionarea produselor",
    version="1.0.0",
    contact={
        "name": "Echipa DodaTech",
        "email": "contact@dodatech.com"
    }
)

class Produs(BaseModel):
    nume: str
    pret: float
    categorie: str

@app.get(
    "/produse",
    summary="Listează toate produsele",
    description="Returnează lista completă de produse cu posibilitatea de filtrare",
    response_description="Lista de produse",
    tags=["Produse"]
)
def lista_produse(
    categorie: str = Query(None, description="Filtrare după categorie"),
    limit: int = Query(10, ge=1, le=100, description="Număr maxim de rezultate")
):
    """Ruta principală pentru listarea produselor."""
    return [{"id": 1, "nume": "Laptop", "pret": 3500}]

@app.post(
    "/produse",
    summary="Creează un produs nou",
    status_code=201,
    tags=["Produse"]
)
def creeaza_produs(p: Produs):
    """Adaugă un produs nou în catalog."""
    return {"id": 2, **p.model_dump()}

from pydantic import Field, BaseModel
from typing import Optional
from datetime import datetime

class Utilizator(BaseModel):
    id: int = Field(..., description="ID unic utilizator")
    nume: str = Field(..., description="Numele complet", example="Ion Popescu")
    email: str = Field(..., description="Adresa de email")
    creat_la: datetime = Field(
        default_factory=datetime.now,
        description="Data creării contului"
    )

class EroareAPI(BaseModel):
    eroare: str
    cod: str

    class Config:
        schema_extra = {
            "example": {
                "eroare": "Produsul nu a fost găsit",
                "cod": "PRODUS_NEGASIT"
            }
        }

pip install flasgger

from flasgger import Swagger
from flask import Flask, jsonify

app = Flask(__name__)
swagger = Swagger(app)

@app.route("/produse/<int:id>")
def produs(id):
    """
    Obține un produs după ID
    ---
    parameters:
      - name: id
        in: path
        type: integer
        required: true
    responses:
      200:
        description: Produsul găsit
        schema:
          type: object
          properties:
            id: {type: integer}
            nume: {type: string}
    """
    return jsonify({"id": id, "nume": "Laptop"})

openapi: "3.0.0"
info:
  title: API Magazin
  version: "1.0.0"
paths:
  /produse:
    get:
      summary: Lista produse
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Produs'