大摇大摆地创建部分

Question

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

USERS
// user specs

POST
// post specs

OTHER
// other specs

Answer 1

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

因此，在您的 "paths" 对象上，您对所有路线进行排序，并在每个路线上添加一个 "tags": ["{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": "...",
        }
    },
}

这在文档中一点也不明显。其实文档很完整，就是缺少索引和一些组织。

大摇大摆地创建部分

Creating sections in swagger

swagger

swagger-ui

openapi