如何在FastAPI中实现API文档自动生成和UI展示

1. FastAPI简介

FastAPI是一个高性能、易于使用、快速编码的 Web 框架，支持异步请求处理。它基于 Python 3.7+，并使用很多 Python 3.7+ 的新特性，包括类型注解、异步/等待语法等。FastAPI 目前已被广泛应用到多个大型项目中，并且越来越受到 Python 社区的关注和认可。

以下是使用FastAPI的优点：

快速的代码生成和运行速度

易于使用，文档齐全，开发效率较高

类型注解强，能大大提高代码的可读性和可维护性

异步请求处理支持

2. FastAPI自动生成文档

2.1 安装FastAPI

如果还未安装，我们需要先安装一下FastAPI。可以使用pip安装：

pip install fastapi

2.2 编写API代码

首先创建一个Python文件，并导入所需模块fastapi、uvicorn。

from fastapi import FastAPI

app = FastAPI()

然后，我们定义一个路由函数，并使用FastAPI的装饰器来告知框架处理HTTP请求和返回响应。

@app.get('/')

async def root():
    return {'message': 'Hello World'}

这里，我们定义一个路由函数root()，使用FastAPI的装饰器@app.get('/')来表示这是一个处理GET请求的路由器。路由函数的返回值是一个字典，表示响应的主体内容。

以下是我们的API代码：

from fastapi import FastAPI

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

2.3 启动应用程序

使用uvicorn运行应用程序：

uvicorn main:app --reload

其中，main是我们Python文件的文件名，app是我们定义的FastAPI实例的名称。--reload选项表示在检测到代码更改时自动重新加载服务器。

用浏览器访问http://localhost:8000/，就可以看到我们返回的 "Hello World" 消息。

2.4 自动生成API文档

FastAPI可以自动生成API文档，可以帮我们快速生成API文档，这样我们就可以更便捷地了解API的使用和接口的参数、返回值等信息。

要启用自动生成的API文档功能，我们需要使用Swagger UI和Redoc框架。它们是两个流行的Web API文档工具，可以帮助我们将API文档清晰地展示给用户。

pip install fastapi[all]

在你的main.py文件中引入FastAPI实例。

from fastapi import FastAPI

app = FastAPI()

导入SwaggerUI和ReDoc。这将在FastAPI中自动创建一些路由以提供API文档界面。

from fastapi.openapi.docs import get_swagger_ui_html

from fastapi.openapi.utils import get_openapi
@app.get('/docs', include_in_schema=False)
async def get_documentation():
    return get_swagger_ui_html(
        openapi_url='/openapi.json',
        title='docs'
    )
@app.get('/openapi.json', include_in_schema=False)
async def get_openapi_endpoint():
    return get_openapi(
        title='Swagger UI',
        version='0.0.1',
        description='This is a sample server',
        routes=app.routes
    )

我们在应用程序中添加了两个新的路由函数get_documentation()和get_openapi_endpoint()。get_documentation()返回一个HTML页面，该页面包含SwaggerUI的JavaScript文件和页面布局代码。该JavaScript文件将自动获取我们的API规范并将其呈现为漂亮的交互文档。按照这种方式生成的SwaggerUI包括路由器的文档，参数和响应的实例信息

3. FastAPI自动生成UI展示

ReDoc是另一个流行的API文档框架，它使用OpenAPI规范，可以在API上创建响应式文档，这使得API的维护变得非常简单。ReDoc还支持一些强大的功能，如快速搜索，按标签过滤，响应代码的复制等。

得到OpenAPI文档后，我们创建了一个基于Redoc的新路由官，用于显示包含API规范的页面。

from fastapi.responses import HTMLResponse

from fastapi.staticfiles import StaticFiles
app.mount('/static', StaticFiles(directory='static'), name='static')
@app.get('/redoc', response_class=HTMLResponse, include_in_schema=False)
async def redoc():
    with open('static/redoc.html', 'r') as f:
        html = f.read()
    return html.replace(
        'https://rebilly.github.io/ReDoc/swagger.yaml',
        '/openapi.json'
    )

3.1 安装ReDoc

为了使用Redoc，我们需要先安装以下依赖项:

pip install aiohttp

pip install async-json
pip install jinja2
pip install python-multipart

同时，我们还需要将Redoc文件放置在应用程序的静态目录中。你可以在官网中下载Redoc，并将它放置在一个名为"static"的文件夹中。

3.2 创建Redoc路由器

为了在FastAPI中使用Redoc，我们需要创建一个新的路由器。这个路由器将使用HTMLResponse作为返回类型并将静态纯文本作为输入。

from fastapi.responses import HTMLResponse

from fastapi.staticfiles import StaticFiles
app.mount('/static', StaticFiles(directory='static'), name='static')
@app.get('/redoc', response_class=HTMLResponse)
async def redoc():
    with open('static/redoc.html', 'r') as f:
        html = f.read()
    return html.replace(
        'https://rebilly.github.io/ReDoc/swagger.yaml',
        '/openapi.json'
    )

这里，我们使用了Python内置的文件对象来读取HTML模板。然后，我们使用返回HTMLResponse的路由器函数进行包装，这使浏览器可以解析和呈现内容。

3.3 生成OpenAPI规范

要在FastAPI中使用Redoc，我们需要提供一个OpenAPI规范。我们可以从get_openapi()函数中获取OpenAPI规范。并创建一个新路由器来呈现这些规范。

from fastapi.openapi.utils import get_openapi

from fastapi import FastAPI, Response
app = FastAPI(
    title='FastAPI Sample App',
    description='This is a simple app to demonstrate how to use FastAPI'
)
@app.get('/openapi.json', include_in_schema=False)
async def generate_openapi():
    return get_openapi(
        title='FastAPI Sample App',
        version='1.0.0',
        description='This is a simple app to demonstrate how to use FastAPI',
        routes=app.routes
    )

这里，我们导入了FastAPI的一个新模块，并调用了get_openapi()函数来生成OpenAPI规范。然后，我们创建一个路由器来呈现这些规范。

3.4 展示自动生成的UI

现在我们已经创建了Redoc路由器和一个生成OpenAPI规范的路由器。我们可以使用Redoc 路由器函数来访问漂亮的、响应式的API文档界面。Redoc使用从生成的OpenAPI规范自动生成文档。这意味着我们可以在API上维护文档，使其更易于协作和多人开发，并且接口变更后可以自动在文档中更新。

在浏览器中访问: http://localhost:8000/redoc, 可以看到自动生成的API文档，如图所示:


4. 总结

在FastAPI中实现自动生成API文档和UI展示非常简单。通过添加少量的Python代码，我们就可以在FastAPI应用程序中自动生成清晰的API文档和响应式文档。这对后端API的开发者和前端API的使用者来说都是非常有用和方便的。