Swagger UI 将我的每个端点都放在“默认”组中。为什么要这么做？

Question

Swagger UI 将我的每个端点放入“默认”组

这是它得到的 JSON（不要问我是怎么得到的）。请注意，没有标签（我还尝试了空列表，而不是杰克逊未序列化的空值）

{
  "openapi": "3.0.3",
  "info": {
    "title": "Api Documentation",
    "description": "Api Documentation",
    "termsOfService": "urn:tos",
    "contact": {    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0"
    },
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://localhost:8080",
      "description": "Api-Gateway-V2"
    }
  ],
  "paths": {
    "/api/v1/hello-world": {
      "get": {
        "summary": "getHelloWorld",
        "operationId": "getHelloWorldUsingGET",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessMessage",
                  "exampleSetFlag": false
                },
                "exampleSetFlag": false
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        }
      }
    },
    "/api/v1/joy": {
      "get": {
        "summary": "getMessageOfJoy",
        "operationId": "getMessageOfJoyUsingGET",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessMessage",
                  "exampleSetFlag": false
                },
                "exampleSetFlag": false
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        }
      }
    },
    "/api/v1/error": {
      "get": {
        "summary": "error",
        "operationId": "errorUsingGET",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/FailureMessage",
                  "exampleSetFlag": false
                },
                "exampleSetFlag": false
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        }
      },
      "put": {
        "summary": "error",
        "operationId": "errorUsingPUT",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/FailureMessage",
                  "exampleSetFlag": false
                },
                "exampleSetFlag": false
              }
            }
          },
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        }
      },
      "post": {
        "summary": "error",
        "operationId": "errorUsingPOST",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/FailureMessage",
                  "exampleSetFlag": false
                },
                "exampleSetFlag": false
              }
            }
          },
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        }
      },
      "delete": {
        "summary": "error",
        "operationId": "errorUsingDELETE",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/FailureMessage",
                  "exampleSetFlag": false
                },
                "exampleSetFlag": false
              }
            }
          },
          "204": {
            "description": "No Content"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      },
      "options": {
        "summary": "error",
        "operationId": "errorUsingOPTIONS",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/FailureMessage",
                  "exampleSetFlag": false
                },
                "exampleSetFlag": false
              }
            }
          },
          "204": {
            "description": "No Content"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      },
      "head": {
        "summary": "error",
        "operationId": "errorUsingHEAD",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/FailureMessage",
                  "exampleSetFlag": false
                },
                "exampleSetFlag": false
              }
            }
          },
          "204": {
            "description": "No Content"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      },
      "patch": {
        "summary": "error",
        "operationId": "errorUsingPATCH",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/FailureMessage",
                  "exampleSetFlag": false
                },
                "exampleSetFlag": false
              }
            }
          },
          "204": {
            "description": "No Content"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      },
      "trace": {
        "summary": "error",
        "operationId": "errorUsingTRACE",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/FailureMessage",
                  "exampleSetFlag": false
                },
                "exampleSetFlag": false
              }
            }
          },
          "204": {
            "description": "No Content"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "FailureMessage": {
        "title": "FailureMessage",
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "exampleSetFlag": false,
            "types": [
              "string"
            ]
          },
          "method": {
            "type": "string",
            "exampleSetFlag": false,
            "types": [
              "string"
            ],
            "enum": [
              "DELETE",
              "GET",
              "HEAD",
              "OPTIONS",
              "PATCH",
              "POST",
              "PUT",
              "TRACE"
            ]
          },
          "request_path": {
            "type": "string",
            "exampleSetFlag": false,
            "types": [
              "string"
            ]
          }
        },
        "exampleSetFlag": false,
        "types": [
          "object"
        ]
      },
      "SuccessMessage": {
        "title": "SuccessMessage",
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "exampleSetFlag": false,
            "types": [
              "string"
            ]
          }
        },
        "exampleSetFlag": false,
        "types": [
          "object"
        ]
      }
    },
    "extensions": {    }
  }
}

结果（这是 UI，因此是屏幕截图）：

我的 Swagger 依赖项是：

<!-- API Gateway -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
            <version>2.0.4</version>
        </dependency>

网关：Java 17、Boot 3

<!-- microservice -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>

微服务：Java 17、Boot 2

我显然希望它按控制器分组，就像通常那样

Swagger 为什么要这样做？

Answer 1

这是我发现的

Swagger UI 按标签对端点进行分组

如果未添加自定义标签（使用

@Tag

），Swagger 将自动为您的控制器类创建一个与该类名称匹配的标签（例如

example-controller

）。类级标签（包括 Swagger 创建的默认标签）将传播到该控制器类中声明的每个端点

如果控制器类或至少其中一个方法有自己的标签，Swagger 将不会为该类创建默认标签。即使您在将

OpenApi

对象提供给 Swagger UI 之前手动删除自定义标记，您仍然不会拥有该默认标记。这意味着那些无标签端点将被分组到“默认”组中