swagger常用注解

最近查看接口文档的时候发现，POST方法中的query没法在swagger中显示，查了才发现这是因为Swagger或OpenAPI规范默认将HTTP POST请求的参数识别为请求体（body）参数，而不是查询字符串（query）参数。这意味着，如果你的POST请求中使用了查询字符串参数并希望在Swagger文档中正确展示它们，你需要明确地通过Swagger注解来指定这些参数是查询参数。因此还是有必要规范swagger注解的。

详细用法

@Api：用在Controller控制器类上value：指定 API 的名称。tags：指定 API 的标签，用于对 API 进行分类。description：描述 API 的功能和作用。produces：指定 API 的响应内容类型。consumes：指定 API 接受的请求内容类型。authorizations：指定 API 的安全认证要求。hidden：指定是否隐藏该 API@ApiOperation：用在Controller控制器类的请求的方法上value：对该操作进行简单的描述，尽量控制在120字符以内notes：对操作的详细描述httpMethod：指定操作使用的HTTP方法类型，可选值 “GET”、“HEAD”、“POST”、“PUT”、“DELETE”、“OPTIONS”和“PATCH”tags：用来给操作打标签，Swagger UI 将在操作列表下面展示 tag 列表，每个 tag 下面展示拥有该 tag 的操作列表。（就是分组）@ApiImplicitParams：用在请求的方法上，表示一组参数说明@ApiImplicitParam：请求方法中参数的说明name：参数名value：参数的汉字说明、解释、用途required：参数是否必须传，布尔类型paramType：参数的类型，即参数存储位置或提交方式· header --> Http的Header携带的参数的获取：@RequestHeader· query --> 请求参数的获取：@RequestParam · path（用于restful接口）--> 请求参数的获取：@PathVariable· body（不常用）· form（不常用）    dataType：参数类型，默认String，其它值dataType="Integer"       defaultValue：参数的默认值@ApiResponses：用在控制器的请求的方法上，对方法的响应结果进行描述@ApiResponse：用于表达一个响应信息code：数字，例如400message：信息，例如"请求参数没填好"response：响应结果封装类，如上例子中的AjaxResponse.class@ApiModel：通常用在描述@RequestBody和@ResponseBody注解修饰的接收参数或响应参数实体类value：属性值，也就是该实体类的描述值，不写默认为实体类的名称，通常描述不清晰才需要value值description：描述值，与value不同，该description为较长描述值parent：用于指定被注解类的父类discriminator：多态情境区分多个子类subTypes：指定被注解类的子类reference：提供对被注解类的引用信息@ApiModelProperty：实体类属性的描述value：注解的默认属性，理解为注释的作用name：指定属性或方法的名称，重写该属性名字allowableValues：指定属性或方法的可接受值范围。access：指定属性或方法的访问规则。notes：提供对属性或方法的额外说明。dataType：指定属性或方法的数据类型。required：指定属性或方法是否为必需。position：指定属性或方法在文档中的位置。hidden：指定属性或方法是否应该在文档中隐藏。example：提供属性或方法的示例值。readOnly（已过时）：指定属性或方法是否为只读。已过时，推荐使用 access 属性。accessMode：指定访问模式，可以是 AUTO、READ_ONLY 或 READ_WRITE。reference：提供属性或方法的引用信息。allowEmptyValue：指定属性或方法是否允许为空值。extensions：指定属性或方法的扩展信息，支持一组扩展属性。AccessMode枚举：属性或方法的访问模式，包括 AUTO、READ_ONLY 和 READ_WRITE。

一个实例

Controller 示例

假设我们有一个处理图书信息的API。

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;@RestController
@Api(value = "Books Controller", tags = {"Books"})
@Slf4j
@RequestMapping("/book")
public class BooksController {@ApiOperation(value = "Get book by ID", notes = "Provides a book's details by its ID")@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "Book ID", required = true, dataType = "long", paramType = "query")})@GetMapping("/books")public BookResponse getBookById(Long id) {// 模拟查询书籍逻辑return new BookResponse(1L, "示例书名", "示例作者", "这是一个示例描述。");}@ApiOperation(value = "Create a new book", notes = "Creates a new book with the provided information")@PostMapping("/books")public BookResponse createBook(@RequestBody BookRequest bookRequest) {// 模拟书籍创建逻辑return new BookResponse(bookRequest.getId(), bookRequest.getTitle(), bookRequest.getAuthor(), bookRequest.getDescription());}
}

Request 示例

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;@Data
@ApiModel(description = "Book creation request")
public class BookRequest {@ApiModelProperty(value = "The ID of the book", required = true)private Long id;@ApiModelProperty(value = "The title of the book", required = true)private String title;@ApiModelProperty(value = "The author of the book")private String author;@ApiModelProperty(value = "The description of the book")private String description;// 构造函数、Getter和Setter方法省略
}

Response 示例

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;@Data
@ApiModel(description = "Book response containing book details")
public class BookResponse {@ApiModelProperty(value = "The ID of the book")private Long id;@ApiModelProperty(value = "The title of the book")private String title;@ApiModelProperty(value = "The author of the book")private String author;@ApiModelProperty(value = "The description of the book")private String description;public BookResponse(Long id, String title, String author, String description) {this.id = id;this.title = title;this.author = author;this.description = description;}// Getter和Setter方法省略
}

在这个例子中，BooksController类包括了两个API端点：一个用于通过ID获取书籍详细信息的GET请求，另一个用于创建新书籍的POST请求。BookRequest和BookResponse类分别用于API请求和响应的数据模型，它们通过使用@ApiModel和@ApiModelProperty注解来提供字段的描述以增强自动生成的Swagger（OpenAPI）文档的可读性。