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：数字，例如400
        message：信息，例如"请求参数没填好"
        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）文档的可读性。