使用Swagger自動產生文檔

Swagger 是什麼。

Swagger 是一個規範和完整的架構，用於產生、描述、調用和可視化 RESTful 風格的 Web 服務。

Springfox 的前身是 swagger-springmvc，是一個開源的 API doc 架構，可以將我們的 Controller 的方法以文檔的形式展現，基於 Swagger。

官網：http://swagger.io/

開源地址：http://springfox.github.io/springfox/

Swagger使用 第一步： 匯入依賴

<!-- Swagger --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.7.0</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.7.0</version></dependency>

第二步： 開啟 @EnableSwagger2註解

@SpringBootApplication@RestController@EnableSwagger2public class DemoApplication {

第三步：訪問 http://localhost:8080/swagger-ui.html




如上攔截了所有controller的API, 如何攔截固定的package，url 的API

第四步：定製url的API
可以一次性攔截所有的介面，也可以分組攔截

@Configurationpublic class Swagger2Configuration {    /*@Beanpublic Docket accessToken() {return new Docket(DocumentationType.SWAGGER_2).groupName("訂單")// 定義組.select() // 選擇那些路徑和 api 會產生 document.apis(RequestHandlerSelectors.basePackage("com.zto.springboot.controller")) // 攔截的包路徑.paths(PathSelectors.regex("/web/.*"))// 攔截的介面路徑.build() // 建立.apiInfo(apiInfo()); // 配置說明}*/@Beanpublic Docket accessToken2() {return new Docket(DocumentationType.SWAGGER_2).groupName("所有介面")// 定義組.select() // 選擇那些路徑和 api 會產生 document.apis(RequestHandlerSelectors.basePackage("com.zto.security.web.controller")) // 攔截的包路徑//.paths(PathSelectors.regex("/user/.*"))// 攔截的介面路徑.paths(PathSelectors.any())  //攔截所有介面.build() // 建立.apiInfo(apiInfo()); // 配置說明}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("xxx項目介面文檔")// 標題.description("xxx項目描述xxx項目描述xxx項目描述xxx項目描述")// 描述.contact(new Contact("xxx", "http://www.baidu.com","xxxxxx@qq.com"))// 聯絡//.termsOfServiceUrl("http://www.roncoo.com")  //服務條款的URL// .license("Apache License Version 2.0")// 開源協議// .licenseUrl("https://github.com/springfox/springfox/blob/master/LICENSE")//地址.version("1.0")// 版本.build();}}

第五步：控制層註解使用說明

@Api：修飾整個類，描述Controller的作用@ApiOperation：描述一個類的一個方法，或者說一個介面@ApiParam：單個參數描述@ApiModel：用對象來接收參數@ApiProperty：用對象接收參數時，描述對象的一個欄位@ApiResponse：HTTP響應其中1個描述@ApiResponses：HTTP響應整體描述@ApiIgnore：使用該註解忽略這個API@ApiError ：發生錯誤返回的資訊@ApiParamImplicitL：一個請求參數@ApiParamsImplicit 多個請求參數

@ApiOperation  

@ApiOperation(value = "新增使用者服務", notes = "新增使用者")@PostMappingpublic User create(@Valid @RequestBody User user, BindingResult errors) {    return user;}

@ApiModelProperty

public class UserQueryCondition {private String username;@ApiModelProperty(value = "使用者年齡起始值")private int age;@ApiModelProperty(value = "使用者年齡終止值")private int ageTo;private String xxx;}

@ApiParam

@ApiOperation(value = "使用者刪除服務", notes = "刪除使用者")@DeleteMapping("/{id:\\d+}")public void delete(@ApiParam("使用者id") @PathVariable String id) {   System.out.println(id);}

最終效果