SpringDoc（Swagger 3）核心注解

一、接口类 / 模块注解标记 ControllerTag作用标记整个 Controller 类说明接口模块的功能示例RestControllerTag (name “用户接口”, description “用户注册 / 登录 / 信息查询”)RequestMapping /api/userpublic class UserController { … }Swagger 2 对应注解Api (tags “用户接口”)二、接口方法注解标记单个接口Operation作用标记接口方法说明接口的功能、参数、返回值等示例PostMapping (“/login”)Operation (summary “用户登录”,description “验证用户名和密码返回登录状态”)public String login (…) { … }Swagger 2 对应注解ApiOperation (value “用户登录”, notes “验证用户名密码”)ApiResponses作用批量定义接口的响应状态码和说明示例GetMapping (“/query”)Operation (summary “查询用户”)ApiResponses ({ApiResponse (responseCode “200”, description “查询成功”),ApiResponse (responseCode “404”, description “用户不存在”)})public User queryUser (…) { … }Swagger 2 对应注解ApiResponses ApiResponse格式类似三、参数注解标记接口参数Parameter作用标记单个参数说明参数含义、是否必传等示例PostMapping (“/register”)public String register (Parameter (description “用户名”, required true)RequestParam String username,Parameter (description “密码”, required true) RequestParam String password) { … }Swagger 2 对应注解ApiParam (name “username”, value “用户名”, required true)ParameterObject作用标记实体类参数自动解析实体类字段示例PostMapping /addpublic User addUser (ParameterObject RequestBody User user) { … }Swagger 2 对应注解无旧版需在实体类加 ApiModel四、实体类 / 字段注解标记 POJOSchema作用标记实体类 / 字段说明含义、是否必传、示例值等示例Schema (description “用户实体类”)public class User {Schema (description “用户名”,requiredMode Schema.RequiredMode.REQUIRED,example “zhangsan”)private String username;Schema (description “年龄”, example “18”)private Integer age;}Swagger 2 对应注解类ApiModel (description “用户实体类”)字段ApiModelProperty (value “用户名”, required true)五、全局配置注解自定义文档信息OpenAPIDefinition作用全局配置文档标题、版本、描述等可替代配置类示例OpenAPIDefinition (info Info (title “我的接口文档”,version “1.0.0”,description “这是基于 SpringDoc 的接口文档”))SpringBootApplicationpublic class SwaggerDemoApplication {…}Swagger 2 对应注解EnableSwagger2 Docket 配置类六、新手必记核心注解优先级1.Tag标记 Controller 模块2.Operation标记接口方法3.Parameter标记单个参数4.Schema标记实体类 / 字段5.ApiResponses标记响应状态码