如何使用 FastAPI 将图像添加到 Swagger UI autodocs？

Question

我想将图像添加到 FastAPI 自动文档（由 Swagger UI 提供），但我不知道如何执行此操作。这是代码：

@api.get(path='/carbon-credit/',
    responses={
        200: {'description': 'Ok',
            "content": {
            "image/jpeg": {
                "example": 'https://picsum.photos/seed/picsum/200/300'
                    }
                }},
        404: {"description": "not found"},
        422: {'description': 'not found 2'},
    },
    name='API for Carbon Credit',
    description="get carbon credit",
    tags=['Images'],
    response_class=Response)

正如您从代码中看到的，我尝试使用 URL 来执行此操作，而我在 ReDoc 和 Swagger UI 中得到的只是文本形式的 URL，而不是实际图像。另外，我想使用存储在本地驱动器中的图像。

Swagger UI 和 ReDoc 的屏幕截图：

我怎样才能做到这一点？

提前致谢。

Answer 1

Swagger UI 和 ReDoc都使用标准 HTML 标签作为description参数。因此，您可以使用description.

@app.get(path='/',
    responses={
        200: {'description': '<img src="https://placebear.com/cache/395-205.jpg" alt="bear">',
    ...

OpenAPI 还支持 markdown 元素（请参阅此处），并将在 Swagger UI/ReDoc 中为您渲染图像。因此，您可以选择使用：

@app.get(path='/',
    responses={
        200: {'description': '![bear](https://placebear.com/cache/395-205.jpg)',
    ...

要使用存储在本地驱动器中的图像，您可以将StaticFiles实例安装到特定路径（比方说/static），以从驱动器中的目录提供静态文件/图像。下面的例子：

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()
app.mount("/static", StaticFiles(directory="static"), name="static")

@app.get(path='/',
    responses={
        200: {'description': '![bear](static/bear.jpg)',
    ...

将图像添加到示例字段

要将图像添加到examples字段中，您可以再次使用该description参数，如下所示。确保通过参数examples而不是example.

@app.get(path='/',
    responses={
        200: {"description": "OK",
               "content": {
                  "image/jpeg": {
                     "schema": {
                        "type": "string",
                        "format": "binary"
                     },
                     "examples": {
                        "sampleImage": {
                           "summary": "A sample image",
                           "description": "![bear](https://placebear.com/cache/395-205.jpg)",
                           "value": ""
                        }
                     }
                  }
               }
            },
        404: {"description": "not found"},
        422: {'description': 'not found 2'},
    },
    ...