FastAPI-Docs空白详解

FastAPI-Docs是一个用于自动生成API文档的工具，它可以高效地生成交互式文档，同时支持多种格式，包括OpenAPI（以前称为Swagger）和ReDoc。在FastAPI中使用FastAPI-Docs非常简单，只需在定义API路由时启用Docs即可。在这篇文章中，我们将从多个方面对FastAPI-Docs进行详细的阐述。

一、使用FastAPI-Docs快速生成API文档

要使用FastAPI-Docs快速生成API文档，我们只需在定义API路由时启用Docs。以下是一个示例代码：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

在这个示例中，我们只定义了一个根路由，它将返回一个JSON响应，并在应用程序启动时使用Uvicorn启动。

要启用FastAPI-Docs，只需要在路由定义中添加一个参数“docs_url”并设置为'/docs'。这将启用一个自动生成的文档站点，网址为'http://localhost:8000/docs'。以下是修改后的代码：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000, docs_url="/docs")

现在访问'http://localhost:8000/docs'就可以看到自动生成的API文档了。在FastAPI中使用FastAPI-Docs非常简单，只需启用路由定义中的“docs_url"参数即可。接下来，我们将进一步了解FastAPI-Docs的各个方面。

二、快速生成OpenAPI文档

在 FastAPI中使用FastAPI-Docs，你可以快速生成 OpenAPI 文档，以便于与其他开发者共享。以下是一个示例代码，演示如何使用FastAPI-Docs生成OpenAPI文档：

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        description="This is a very custom OpenAPI schema",
        routes=app.routes,
    )
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app.openapi = custom_openapi

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000, docs_url="/docs")

在这个示例中，我们定义了一个名为 custom_openapi 的函数。该函数作为 app.openapi 的值设置，这是一个包含 OpenAPI Schema 的字典。在此示例中，我们设置了一个自定义标题、自定义版本和自定义说明，以及将 app.routes 作为参数传递给 FastAPI-Docs。如果你希望使用 FastAPI-Docs 更改你的 API 的文档，那么这非常有用。

三、文档页面的定制

FastAPI-Docs不仅支持一键生成文档，还支持自定义文档页面的外观和行为。以下是示例代码，演示如何自定义文档页面：

from fastapi import FastAPI, Response
from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html
from fastapi.responses import HTMLResponse

app = FastAPI()

@app.route("/redoc")
async def redoc(request: Request):
    return get_redoc_html(
        openapi_url="/openapi.json",
        title="Custom Redoc",
        redoc_js_url="/static/redoc.standalone.js",
        redoc_favicon_url="/static/favicon.png",
    )

@app.route("/docs", methods=["GET"])
async def get_docs(request: Request):
    return get_swagger_ui_html(
        openapi_url="/openapi.json",
        title="Custom Swagger UI",
        swagger_js_url="/static/swagger-ui-bundle.js",
        swagger_css_url="/static/swagger-ui.css",
        swagger_favicon_url="/static/favicon.png",
    )

@app.route("/openapi.json")
async def get_open_api_endpoint(request: Request):
    return JSONResponse(app.openapi())

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000, docs_url="/docs")

在这个示例中，我们定义三个路由，'redoc'，'docs'和'openapi.json'。在'get_docs'路由中，我们返回响应，其中包含自定义的Swagger UI。在'redoc'路由中，我们返回响应，其中包含自定义的Redoc实例。在'get_open_api_endpoint'路由中，我们返回包含OpenAPI Schema的响应。上面这个示例代码的网址为'http://localhost:8000/redoc'和'http://localhost:8000/docs'。

四、在文档中附加模型类

在 FastAPI-Docs 中，你可以将模型类附加到文档中。以下是一个示例代码，演示如何在文档中附加模型类：

from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None

app = FastAPI()

@app.post("/items/")
async def create_item(item: Item):
    return item

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000, docs_url="/docs", schema_url="/schema")

在这个示例中，我们定义了一个名为 Item 的模型类，并将其作为参数传递给 API 路由。FastAPI-Docs将自动生成与 Item 模型类相关的 JSON Schema。还可以通过在启动应用程序时设置 "schema_url" 来生成该模式。这将返回一个包含 JSON Schema 的响应，网址为'http://localhost:8000/schema'。

五、使用FastAPI-Docs自定义认证和授权页面

FastAPI-Docs 还支持自定义认证和授权页面。以下是一个示例代码，演示如何自定义认证和授权页面：

from fastapi import FastAPI
from fastapi.openapi.docs import (get_swagger_ui_html, get_redoc_html)
from fastapi.openapi.utils import get_openapi
from fastapi.responses import HTMLResponse, JSONResponse

app = FastAPI()

@app.get("")
async def read_root():
    return {"Hello": "World"}

@app.post("/token")
async def login():
    return {"access_token": "johndoe_token"}

# Documentation URLs
@app.get("/docs", response_class=HTMLResponse)
async def get_documentation():
    return get_swagger_ui_html(
        openapi_url="/openapi.json",
        title="docs"
    )

@app.get("/redoc", response_class=HTMLResponse)
async def get_documentation():
    return get_redoc_html(
        openapi_url="/openapi.json",
        title="redoc"
    )

@app.get("/openapi.json", response_class=JSONResponse)
async def get_openapi():
    return get_openapi(
        title="Custom Title",
        version="2.5.0",
        description="This is a custom OpenAPI schema",
        routes=app.routes,
    )

if __name__ == '__main__':
    import uvicorn
    uvicorn.run(app, port=8000, host="0.0.0.0", debug=True, use_colors=True)

在这个示例中，我们定义了两个认证和授权路由 ("/" 和 "/token")，以及三个文档路由 ("/docs"、"/redoc" 和 "/openapi.json")。在"/token"挂载的路由中验证用户，若验证成功，我们返回一个授权令牌。API 文档将显示一个“Authorize”按钮，就像默认情况下一样，但是我们在“Authorize”框中输入的“Bearer ”后面输入上面返回的授权令牌。使用 FastAPI-Docs，我们可以轻松地自定义认证和授权页面。