使用Swagger生成Web API文檔
高質量的API文檔在系統開發的過程中非常重要。本節介紹什么是Swagger，如何在Spring Boot項目中集成Swagger構建RESTful API文檔，以及為Swagger配置Token等通用參數。
1.什么是Swagger
Swagger是一個規范和完整的框架，用于生成、描述、調用和可視化RESTful風格的Web服務，是非常流行的API表達工具。
普通的API文檔存在以下問題：
1）由于接口眾多，并且細節復雜（需要考慮不同的HTTP請求類型、HTTP頭部信息、HTTP請求內容等），創建這樣一份高質量的文檔是一件非常煩瑣的工作。
2）隨著需求的不斷變化，接口文檔必須同步修改，就很容易出現文檔和業務不一致的情況。為了解決這些問題，Swagger應運而生，它能夠自動生成完善的RESTful API文檔，并根據后臺代碼的修改同步更新。這樣既可以減少維護接口文檔的工作量，又能將說明內容集成到實現代碼中，讓維護文檔和修改代碼合為一體，實現代碼邏輯與說明文檔的同步更新。另外，Swagger也提供了完整的測試頁面來調試API，讓API測試變得輕松、簡單。
2.使用Swagger生成Web API文檔
在Spring Boot項目中集成Swagger同樣非常簡單，只需在項目中引入springfox-swagger2和springfox-swagger-ui依賴即可。下面就以之前的用戶管理模塊接口為例來感受Swagger的魅力。
步驟01 配置Swagger的依賴。
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>3.0.0</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>3.0.0</version></dependency>在上面的示例中，在項目pom.xml配置文件中引入了springfox-swagger2和springfox-swagger-ui兩個依賴包。其中swagger2是主要的文檔生成組件，swagger-ui為頁面顯示組件。
步驟02 創建Swagger2配置類。
@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {@Beanpublic Docket createRestApi () {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("Spring boot中使用Swagger2構建RESTful APIs").description("相關文章請關注:https://blog.csdn.net/weixin_45627039?spm=1000.2115.3001.5343").termsOfServiceUrl("https://blog.csdn.net/weixin_45627039?spm=1000.2115.3001.5343")// .contact("架構師精進").version("1.0").build();}/*** swagger增加url映射* @param registry*/@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars");}
}
在上面的示例中，我們在SwaggerConfig的類上添加了@Configuration和@EnableSwagger2兩個注解。
@Configuration注解讓Spring Boot來加載該類配置。
@EnableSwagger2注解啟用Swagger2，通過配置一個Docket Bean，來配置映射路徑和要掃描的接口所在的位置。
apiInfo主要配置Swagger2文檔網站的信息，比如網站的標題、網站的描述、使用的協議等。
需要注意的是：
1）basePackage可以在SwaggerConfig中配置com.weiz.example01.controller，也可以在啟動器ComponentScan中配置。
2）需要在SwaggerConfig中配置Swagger的URL映射地址：/swagger-ui.html。
步驟03 添加文檔說明內容。
上面的配置完成之后，接下來需要在API上增加內容說明。我們直接在之前的用戶管理模塊的UserController中增加相應的接口內容說明，代碼如下：
@Api(tags = {"用戶接口"})@RestControllerpublic class UserController {@ApiOperation(value="創建用戶", notes="根據User對象創建用戶")@PostMapping(value ="user")public JSONResult save(@RequestBody User user){System.out.println("用戶創建成功:" + user.getName());return JSONResult.ok(201, "用戶創建成功");}@ApiOperation(value="更新用戶詳細信息", notes="根據id來指定更新對象，并根據傳過來的user信息來更新用戶詳細信息")@PutMapping(value = "user")public JSONResult update(@RequestBody User user) {System.out.println("用戶修改成功:" + user.getName());return JSONResult.ok(203, "用戶修改成功");}@ApiOperation(value="刪除用戶", notes="根據url的id來指定刪除對象")@ApiImplicitParam(name = "userId", value = "用戶ID", required = true, dataType ="Long", paramType = "query")@DeleteMapping("user/{userId}")public JSONResult delete(@PathVariable String userId) {System.out.println("用戶刪除成功:" + userId);return JSONResult.ok(204,"用戶刪除成功");}}
在上面的示例中，主要為UserController中的接口增加了接口信息描述，包括接口的用途、請求參數說明等。
1）@Api注解：用來給整個控制器（Controller）增加說明。
2）@ApiOperation注解：用來給各個API方法增加說明。
3）@ApiImplicitParams、@ApiImplicitParam注解：用來給參數增加說明。
步驟04 查看生成的API文檔。
完成上面的配置和代碼修改之后，Swagger 2就集成到Spring Boot項目中了。接下來啟動項目，在瀏覽器中訪問http://localhost:8080/swagger-ui.html，Swagger會自動構建接口說明文檔，如圖所示。
Swagger自動將用戶管理模塊的全部接口信息展現出來，包括接口功能說明、調用方式、請求參數、返回數據結構等信息。
在Swagger頁面上，我們發現每個接口描述右側都有一個按鈕try it out，單擊try it out按鈕即可調用該接口進行測試。如圖所示，在獲取人員信息的接口上單擊try it out按鈕，輸入userId的請求參數“2001”，單擊Execute按鈕就會將請求發送到后臺，從而進行接口驗證測試。
3.為Swagger添加token參數
很多時候，客戶端在調用API時需要在HTTP的請求頭攜帶通用參數，比如權限驗證的token參數等。但是Swagger是怎么描述此類參數的呢？接下來通過示例演示如何為Swagger添加固定的請求參數。
其實非常簡單，修改Swagger2Config配置類，利用ParameterBuilder構成請求參數。具體示例代碼如下：
@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {@Beanpublic Docket createRestApi() {ParameterBuilder parameterBuilder = new ParameterBuilder();List<Parameter> parameters = new ArrayList<Parameter>();parameterBuilder.name("token").description("token令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build().globalOperationParameters(parameters);}...
}
在上面的示例中，通過ParameterBuilder類把token作為全局統一的參數添加到HTTP的請求頭中。系統所有的API都會統一加上此參數。
完成之后重新啟動應用，再次查看接口，如圖所示，我們可以看到接口參數中已經支持發送token請求參數。
人員管理模塊中的所有API都統一加上了token參數，調用時Swagger會將token參數自動加入HTTP的請求頭。
4.Swagger常用注解
Swagger提供了一系列注解來描述接口信息，包括接口說明、請求方法、請求參數、返回信息等，常用注解如表所示。
在實際項目中，Swagger除了提供@ApiImplicitParams注解描述簡單的參數之外，還提供了用于對象參數的@ApiModel和@ApiModelProperty兩個注解，用于封裝的對象作為傳入參數或返回數據。
@ApiModel負責描述對象的信息
@ApiModelProperty負責描述對象中屬性的相關內容
以上是在項目中常用的一些注解，利用這些注解就可以構建出清晰的API文檔。
