如何使用 FastAPI 将图像添加到 Swagger UI 自动文档？

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，而不是实际图像。另外，我想使用存储在本地驱动器中的图像。

我如何才能做到这一点？

先谢谢你。

Answer 1

Swagger UI和ReDoc都使用标准的超文本标记语言标记描述参数。因此，您可以使用描述添加图像。

@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)',
    ...

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

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)',
    ...

要将图像添加到示例字段，您可以再次使用描述参数，如下所示。确保通过示例参数而不是示例执行此操作。

@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'},
    },
    ...