做竞价网站,房产中介网站怎么做,找聊城做网站,长沙麓谷建设发展有限公司网站最近查看接口文档的时候发现#xff0c;POST方法中的query没法在swagger中显示#xff0c;查了才发现这是因为Swagger或OpenAPI规范默认将HTTP POST请求的参数识别为请求体#xff08;body#xff09;参数#xff0c;而不是查询字符串#xff08;query#xff09;参数。…最近查看接口文档的时候发现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指定是否隐藏该 APIApiOperation用在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其它值dataTypeInteger defaultValue参数的默认值ApiResponses用在控制器的请求的方法上对方法的响应结果进行描述ApiResponse用于表达一个响应信息code数字例如400message信息例如请求参数没填好response响应结果封装类如上例子中的AjaxResponse.classApiModel通常用在描述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 books 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注解来提供字段的描述以增强自动生成的SwaggerOpenAPI文档的可读性。
