{"id":35081128,"url":"https://github.com/0bvim/fastapi_doc","last_synced_at":"2026-05-18T20:04:31.256Z","repository":{"id":326746615,"uuid":"1024559497","full_name":"0bvim/fastapi_doc","owner":"0bvim","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-22T22:45:14.000Z","size":4,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-24T10:18:50.608Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0bvim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-22T22:39:39.000Z","updated_at":"2025-07-22T22:45:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/0bvim/fastapi_doc","commit_stats":null,"previous_names":["0bvim/fastapi_doc"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/0bvim/fastapi_doc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0bvim%2Ffastapi_doc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0bvim%2Ffastapi_doc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0bvim%2Ffastapi_doc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0bvim%2Ffastapi_doc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0bvim","download_url":"https://codeload.github.com/0bvim/fastapi_doc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0bvim%2Ffastapi_doc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33189279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-18T09:27:30.708Z","status":"ssl_error","status_checked_at":"2026-05-18T09:27:28.300Z","response_time":71,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-27T12:58:09.060Z","updated_at":"2026-05-18T20:04:31.250Z","avatar_url":"https://github.com/0bvim.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FastAPI Documentation Demo\n\nA demonstration project showcasing FastAPI's automatic API documentation generation using **Swagger UI** and **ReDoc**. This project illustrates how to create well-documented APIs with deprecated endpoints, multiple API versions, and comprehensive docstrings.\n\n## 🎯 Purpose\n\nThis project demonstrates:\n- **Automatic API Documentation**: How FastAPI generates interactive documentation\n- **Swagger UI Integration**: Interactive API testing interface at `/docs`\n- **ReDoc Integration**: Clean, responsive API documentation at `/redoc`\n- **Endpoint Deprecation**: How to properly mark and document deprecated endpoints\n- **API Versioning**: Managing multiple versions of the same endpoint\n- **Rich Docstrings**: Writing comprehensive endpoint documentation\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Python 3.7+\n- [uv](https://docs.astral.sh/uv/) (Fast Python package manager)\n\n### Installing uv\n\nIf you don't have uv installed yet:\n\n**macOS and Linux:**\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n**Windows:**\n```bash\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\n**Alternative (with pip):**\n```bash\npip install uv\n```\n\n### Installation\n\n1. **Clone or download this project**\n   ```bash\n   cd fastapi\n   ```\n\n2. **Install dependencies using uv**\n   ```bash\n   uv sync\n   ```\n   \n   Or if you don't have a `pyproject.toml`, install directly:\n   ```bash\n   uv add fastapi uvicorn\n   ```\n\n### Running the Application\n\nStart the development server using uv:\n```bash\nuv run uvicorn main:app --reload\n```\n\nThe API will be available at: `http://localhost:8000`\n\n## 📚 Accessing Documentation\n\nOnce the server is running, you can access the automatic documentation at:\n\n### Swagger UI (Interactive)\n- **URL**: http://localhost:8000/docs\n- **Features**: \n  - Interactive API testing\n  - Try endpoints directly in the browser\n  - Automatic request/response examples\n  - Schema validation\n\n### ReDoc (Clean Documentation)\n- **URL**: http://localhost:8000/redoc\n- **Features**:\n  - Clean, responsive design\n  - Comprehensive API overview\n  - Detailed schema documentation\n  - Better for sharing with stakeholders\n\n### OpenAPI Schema (JSON)\n- **URL**: http://localhost:8000/openapi.json\n- **Purpose**: Raw OpenAPI specification for integration with other tools\n\n## 🔍 API Endpoints\n\n| Endpoint | Method | Status | Description |\n|----------|--------|--------|-------------|\n| `/` | GET | ✅ Active | Health check endpoint |\n| `/v1/data` | GET | ⚠️ Deprecated | Legacy data endpoint (will be removed) |\n| `/v2/data` | GET | ✅ Active | Current data endpoint |\n\n## 🛠 How It Works\n\n### 1. FastAPI App Configuration\n\n```python\napp = FastAPI(\n    title=\"Deprecation Demo API\",\n    description=\"A simple API to demonstrate how to deprecate an endpoint.\",\n    version=\"1.0.0\",\n)\n```\n\nThe `FastAPI()` constructor accepts metadata that appears in the generated documentation:\n- **title**: Main title of your API\n- **description**: Overview description\n- **version**: API version number\n\n### 2. Automatic Documentation Generation\n\nFastAPI automatically generates documentation from:\n- **Function signatures**: Parameter types and return types\n- **Docstrings**: Detailed endpoint descriptions\n- **Type hints**: Request/response schemas\n- **Pydantic models**: Data validation and serialization\n\n### 3. Deprecation Handling\n\n```python\n@app.get(\"/v1/data\", deprecated=True)\n```\n\nThe `deprecated=True` parameter:\n- Marks the endpoint as deprecated in documentation\n- Shows a strikethrough in Swagger UI\n- Adds deprecation warnings in ReDoc\n- Helps API consumers migrate to newer versions\n\n### 4. Rich Docstrings\n\n```python\nasync def get_old_data():\n    \"\"\"\n    **This endpoint is deprecated and will be removed in a future version.**\n\n    Please use the new `/v2/data` endpoint instead.\n\n    This endpoint retrieves legacy data.\n    \"\"\"\n```\n\nDocstrings support:\n- **Markdown formatting**: Bold, italic, links, etc.\n- **Multi-line descriptions**: Detailed explanations\n- **Usage instructions**: How to use the endpoint\n- **Migration guidance**: For deprecated endpoints\n\n## 🎨 Documentation Features Demonstrated\n\n### Swagger UI Features\n- **Interactive Testing**: Click \"Try it out\" to test endpoints\n- **Request Examples**: Automatic generation of example requests\n- **Response Codes**: All possible HTTP status codes\n- **Schema Validation**: Real-time validation of requests\n\n### ReDoc Features  \n- **Responsive Design**: Works on desktop and mobile\n- **Code Samples**: Multiple programming language examples\n- **Deep Linking**: Direct links to specific endpoints\n- **Download Specs**: Export OpenAPI specification\n\n### Advanced Documentation\n- **Deprecation Warnings**: Visual indicators for deprecated endpoints\n- **Version Management**: Clear separation between API versions\n- **Error Documentation**: Comprehensive error response schemas\n- **Authentication**: Support for various auth schemes (when implemented)\n\n## 🔧 Customization Options\n\n### Using with uv project management\nIf you want to use this with a full uv project setup:\n```bash\nuv init\nuv add fastapi uvicorn\nuv run uvicorn main:app --reload\n```\n\n### Custom Documentation URLs\n```python\napp = FastAPI(docs_url=\"/api/docs\", redoc_url=\"/api/redoc\")\n```\n\n### Disable Documentation (Production)\n```python\napp = FastAPI(docs_url=None, redoc_url=None)\n```\n\n### Custom OpenAPI Schema\n```python\nfrom fastapi.openapi.utils import get_openapi\n\ndef custom_openapi():\n    if app.openapi_schema:\n        return app.openapi_schema\n    openapi_schema = get_openapi(\n        title=\"Custom API\",\n        version=\"2.5.0\",\n        description=\"Custom OpenAPI schema\",\n        routes=app.routes,\n    )\n    app.openapi_schema = openapi_schema\n    return app.openapi_schema\n\napp.openapi = custom_openapi\n```\n\n## 📖 Learning Resources\n\n- [FastAPI Documentation](https://fastapi.tiangolo.com/)\n- [OpenAPI Specification](https://swagger.io/specification/)\n- [ReDoc Documentation](https://redoc.ly/)\n- [Swagger UI Documentation](https://swagger.io/tools/swagger-ui/)\n\n## 📦 Dependencies\n\nThis project includes a `requirements.txt` file for compatibility with traditional pip workflows, but **uv is the recommended package manager** for faster dependency resolution and installation.\n\n## 🤝 Contributing\n\nThis is a demonstration project. Feel free to:\n- Add more endpoints with different features\n- Implement request/response models with Pydantic\n- Add authentication examples\n- Include error handling demonstrations\n\nWhen contributing, please use `uv` for dependency management:\n```bash\nuv add \u003cnew-dependency\u003e\nuv run \u003ccommand\u003e\n```\n\n## 📄 License\n\nThis project is for educational purposes and is free to use and modify. ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0bvim%2Ffastapi_doc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0bvim%2Ffastapi_doc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0bvim%2Ffastapi_doc/lists"}