## 一、概述 Springfox是一個通過掃描代碼提取代碼中的信息，生成API文檔的工具。 #### **OAS** API文檔的規范化需求，導致了OpenAPI Specification的誕生； OAS是OpenAPI Specification的簡稱，可以翻譯為OpenAPI規范，它是定義API的一種規范，它的前身是Swagger規范。 OAS定義了一種書寫API的一種格式，大家通過遵從同一種格式規范達到API文檔的統一。狹義上理解，它用于描述一整套API接口，包括一個接口是GET還是POST請求啊，有哪些參數哪些header等等，它在設計的時候通常是YAML格式，這種格式書寫起來比較方便，而在網絡中傳輸時又會以json形式居多，因為json的通用性比較強。OpenAPI Specification已經在2015年捐獻給了Linux基金會，現在已經成為RESTful API的世界標準。 #### **Swagger** Swagger是一個工具、一個項目、一個流行的API開發框架(當然，我們上面也說了Swagger是規范，但是后面演變成了OAS)，這個框架以OAS為基礎，對整個API的開發周期都提供了相應的解決方案，是一個非常龐大的項目（包括Swagger Editor、Swagger UI、Swagger Codegen、Swagger Inspector）。 #### **Springfox** Springfox是踐行OAS的一個項目，它將Swagger融合進流行的Spring框架，根據OpenAPI規范，幫助開發者自動生成API文檔。 因此，我們在Springboot項目只需要使用Springfox即可； ## 二、Springfox使用（基于最新V3） 1、首先加入依賴： ``` <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> ``` 2、在應用的主類上面，增加標注：@EnableOpenApi；  3、加入springFox的對象配置（可選，非必須）； ``` @Configuration public class RaySwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30).pathMapping("/") // 定義是否開啟swagger，false為關閉，可以通過變量控制 .enable(true) // 將api的元信息設置為包含在json ResourceListing響應中。 .apiInfo(apiInfo()) // 選擇哪些接口作為swagger的doc發布 .select().apis(RequestHandlerSelectors.basePackage("com.ray.app").and(RequestHandlerSelectors.basePackage("org.ray.rayframework"))).paths(PathSelectors.any()).build().groupName("Rayframework") // 支持的通訊協議集合 .protocols(Set.of("https", "http")); } /** * API 頁面上半部分展示信息 */ private ApiInfo apiInfo() { return new ApiInfoBuilder().version("1.0.0").title("Rayframework API接口文檔").description("Rayframework Application").contact(new Contact("Rayframework", null, "4170804@qq.com")).build(); } } ``` 4、訪問SwaggerUI： [http://localhost:8090/swagger-ui/index.html](http://localhost:8090/swagger-ui/index.html) 5、注解說明； @Api：用在請求的類上，表示對類的說明 tags="說明該類的作用，可以在UI界面上看到的注解" @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數的各個方面 name：參數名 value：參數的漢字說明、解釋 required：參數是否必須傳 paramType：參數放在哪個地方 · header --> 請求參數的獲取：@RequestHeader · query --> 請求參數的獲取：@RequestParam · path（用于restful接口）--> 請求參數的獲取：@PathVariable · body（不常用） · form（不常用） dataType：參數類型，默認String，其它值dataType="Integer" defaultValue：參數的默認值 @ApiResponse：用在@ApiResponses中，一般用于表達一個錯誤的響應信息 code：數字，例如400 message：信息，例如"請求參數沒填好" response：拋出異常的類 @ApiModel：用于響應類上，表示一個返回響應數據的信息 （這種一般用在post創建的時候，使用@RequestBody這樣的場景， 請求參數無法使用@ApiImplicitParam注解進行描述的時候） @ApiModelProperty：用在屬性上，描述響應類的屬性