最近查看接口文檔的時(shí)候發(fā)現(xiàn)，POST方法中的query沒法在swagger中顯示，查了才發(fā)現(xiàn)這是因?yàn)镾wagger或OpenAPI規(guī)范默認(rèn)將HTTP POST請(qǐng)求的參數(shù)識(shí)別為請(qǐng)求體（body）參數(shù)，而不是查詢字符串（query）參數(shù)。這意味著，如果你的POST請(qǐng)求中使用了查詢字符串參數(shù)并希望在Swagger文檔中正確展示它們，你需要明確地通過Swagger注解來指定這些參數(shù)是查詢參數(shù)。因此還是有必要規(guī)范swagger注解的。

詳細(xì)用法

@Api：用在Controller控制器類上value：指定 API 的名稱。tags：指定 API 的標(biāo)簽，用于對(duì) API 進(jìn)行分類。description：描述 API 的功能和作用。produces：指定 API 的響應(yīng)內(nèi)容類型。consumes：指定 API 接受的請(qǐng)求內(nèi)容類型。authorizations：指定 API 的安全認(rèn)證要求。hidden：指定是否隱藏該 API@ApiOperation：用在Controller控制器類的請(qǐng)求的方法上value：對(duì)該操作進(jìn)行簡單的描述，盡量控制在120字符以內(nèi)notes：對(duì)操作的詳細(xì)描述httpMethod：指定操作使用的HTTP方法類型，可選值 “GET”、“HEAD”、“POST”、“PUT”、“DELETE”、“OPTIONS”和“PATCH”tags：用來給操作打標(biāo)簽，Swagger UI 將在操作列表下面展示 tag 列表，每個(gè) tag 下面展示擁有該 tag 的操作列表。（就是分組）@ApiImplicitParams：用在請(qǐng)求的方法上，表示一組參數(shù)說明@ApiImplicitParam：請(qǐng)求方法中參數(shù)的說明name：參數(shù)名value：參數(shù)的漢字說明、解釋、用途required：參數(shù)是否必須傳，布爾類型paramType：參數(shù)的類型，即參數(shù)存儲(chǔ)位置或提交方式· header --> Http的Header攜帶的參數(shù)的獲取：@RequestHeader· query --> 請(qǐng)求參數(shù)的獲取：@RequestParam · path（用于restful接口）--> 請(qǐng)求參數(shù)的獲取：@PathVariable· body（不常用）· form（不常用）    dataType：參數(shù)類型，默認(rèn)String，其它值dataType="Integer"       defaultValue：參數(shù)的默認(rèn)值@ApiResponses：用在控制器的請(qǐng)求的方法上，對(duì)方法的響應(yīng)結(jié)果進(jìn)行描述@ApiResponse：用于表達(dá)一個(gè)響應(yīng)信息code：數(shù)字，例如400message：信息，例如"請(qǐng)求參數(shù)沒填好"response：響應(yīng)結(jié)果封裝類，如上例子中的AjaxResponse.class@ApiModel：通常用在描述@RequestBody和@ResponseBody注解修飾的接收參數(shù)或響應(yīng)參數(shù)實(shí)體類value：屬性值，也就是該實(shí)體類的描述值，不寫默認(rèn)為實(shí)體類的名稱，通常描述不清晰才需要value值description：描述值，與value不同，該description為較長描述值parent：用于指定被注解類的父類discriminator：多態(tài)情境區(qū)分多個(gè)子類subTypes：指定被注解類的子類reference：提供對(duì)被注解類的引用信息@ApiModelProperty：實(shí)體類屬性的描述value：注解的默認(rèn)屬性，理解為注釋的作用name：指定屬性或方法的名稱，重寫該屬性名字allowableValues：指定屬性或方法的可接受值范圍。access：指定屬性或方法的訪問規(guī)則。notes：提供對(duì)屬性或方法的額外說明。dataType：指定屬性或方法的數(shù)據(jù)類型。required：指定屬性或方法是否為必需。position：指定屬性或方法在文檔中的位置。hidden：指定屬性或方法是否應(yīng)該在文檔中隱藏。example：提供屬性或方法的示例值。readOnly（已過時(shí)）：指定屬性或方法是否為只讀。已過時(shí)，推薦使用 access 屬性。accessMode：指定訪問模式，可以是 AUTO、READ_ONLY 或 READ_WRITE。reference：提供屬性或方法的引用信息。allowEmptyValue：指定屬性或方法是否允許為空值。extensions：指定屬性或方法的擴(kuò)展信息，支持一組擴(kuò)展屬性。AccessMode枚舉：屬性或方法的訪問模式，包括 AUTO、READ_ONLY 和 READ_WRITE。

一個(gè)實(shí)例

Controller 示例

假設(shè)我們有一個(gè)處理圖書信息的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, "示例書名", "示例作者", "這是一個(gè)示例描述。");}@ApiOperation(value = "Create a new book", notes = "Creates a new book with the provided information")@PostMapping("/books")public BookResponse createBook(@RequestBody BookRequest bookRequest) {// 模擬書籍創(chuàng)建邏輯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;// 構(gòu)造函數(shù)、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方法省略
}

在這個(gè)例子中，BooksController類包括了兩個(gè)API端點(diǎn)：一個(gè)用于通過ID獲取書籍詳細(xì)信息的GET請(qǐng)求，另一個(gè)用于創(chuàng)建新書籍的POST請(qǐng)求。BookRequest和BookResponse類分別用于API請(qǐng)求和響應(yīng)的數(shù)據(jù)模型，它們通過使用@ApiModel和@ApiModelProperty注解來提供字段的描述以增強(qiáng)自動(dòng)生成的Swagger（OpenAPI）文檔的可讀性。