最近查看接口文档的时候发现,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)文档的可读性。