swagger - Swagger 创建部分

Question

我正在编写一个 swagger 规范，并且我有三个独立的端点。我如何在文档中将它们分开？我想明确区分示例:用户、帖子和其他。所以每个人都会有一个 CRUD 描述并显示在 swagger UI 中，它看起来像:

USERS
// user specs

POST
// post specs

OTHER
// other specs

Answer 1

您需要使用标签来完成此操作。

因此，在您的“路径”对象上，您对所有路线进行排序，并在每一个路线上添加一个“标签”:[“{resource}”]应该分组的地方。

例如:

"paths": {
    "/users": {
        "get": {
            "tags": ["User"],
            "description": "...",
        },
        "post": {
            "tags": ["User"],
            "description": "...",
        }
    },

    "/posts": {
        "get": {
            "tags": ["Post"],
            "description": "...",
        },
        "post": {
            "tags": ["Post"],
            "description": "...",
        }
    },

    "/other": {
        "get": {
            "tags": ["Other"],
            "description": "...",
        },
        "post": {
            "tags": ["Other"],
            "description": "...",
        }
    },
}

这在文档中一点也不明显。实际上文档非常完整，但缺少索引和一些组织。