swagger - 大摇大摆地创建部分

Question

我正在写一个招摇规范，我有三个独立的端点。如何在我的文档中将它们分开？我想明确区分示例：用户、帖子和其他。所以每个人都会有一个 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": "...",
        }
    },
}

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