一、簡單介紹
Swagger是一個實現了OpenAPI(OpenAPI Specification)規范的工具集。OpenAPI是Linux基金會的一個項目，試圖通過定義一種用來描述API格式或API定義的語言，來規范RESTful服務開發過程。
swagger大大方便了前后端開發人員，用過的人都說好。但是也有一些人並未體驗過swagger，還在苦苦的手寫接口文檔，麻煩又不規范；還有一些人雖然用過，但是只是朦朦朧朧，看別人怎么用直接就CV過來用了，使用的很碎片，不系統。我之前就是這個樣子，只知道添加個依賴，啟動項目后訪問：localhost:8080/swagger-ui.html，就能看到生成的文檔了，很是簡單。
一次我看到生成的文檔上總是多出來一個basic-error-controller，強迫症犯了，就想要把它弄掉，於是順便看了下swagger的配置，在這里記錄一下。
看官方的說明：
Swagger包含的工具集：
- Swagger編輯器： Swagger Editor允許您在瀏覽器中編輯YAML中的OpenAPI規范並實時預覽文檔。
- Swagger UI： Swagger UI是HTML，Javascript和CSS資產的集合，可以從符合OAS標准的API動態生成漂亮的文檔。
- Swagger Codegen：允許根據OpenAPI規范自動生成API客戶端庫（SDK生成），服務器存根和文檔。
- Swagger Parser：用於解析來自Java的OpenAPI定義的獨立庫
- Swagger Core：與Java相關的庫，用於創建，使用和使用OpenAPI定義
- Swagger Inspector（免費）： API測試工具，可讓您驗證您的API並從現有API生成OpenAPI定義
- SwaggerHub（免費和商業）： API設計和文檔，為使用OpenAPI的團隊構建。
二、入門案例
SpringBoot已經集成了Swagger，使用簡單注解即可生成swagger的API文檔。
1.引入依賴
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2.編寫配置
@Configuration
@EnableSwagger2 // Swagger的開關，表示已經啟用Swagger
public class SwaggerConfig {
@Bean
public Docket api() {
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.host("localhost:8081")// 不配的話，默認當前項目端口
.apiInfo(apiInfo())
.pathMapping("/")
.select() // 選擇哪些路徑和api會生成document
.apis(RequestHandlerSelectors.any())// 對所有api進行監控
// .apis(RequestHandlerSelectors.basePackage("com.hanstrovsky.controller"))// 選擇監控的package
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 只監控有ApiOperation注解的接口
//不顯示錯誤的接口地址
.paths(Predicates.not(PathSelectors.regex("/error.*")))//錯誤路徑不監控
.paths(PathSelectors.regex("/.*"))// 對根下所有路徑進行監控
.build();
return docket;
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("XXXX項目接口文檔")
.contact(new Contact("Hanstrovsky", "www.hanstrovsky.com", "Hanstrovsky@gmail.com"))
.description("這是用Swagger動態生成的接口文檔")
.termsOfServiceUrl("NO terms of service")
.license("The Apache License, Version 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.version("1.0")
.build();
}
}
3.啟動測試
啟動服務，訪問：http://localhost:8081/swagger-ui.html
就能看到swagger-ui為我們提供的API頁面了：
可以看到我們編寫的接口，任意點擊一個，即可看到接口的詳細信息：
可以看到詳細的接口聲明，包括：
- 請求方式：
- 請求路徑
- 請求參數
- 響應等信息
點擊右上角的try it out!還可以測試接口。
三、常用注解
剛才的文檔說明中，是swagge-ui根據接口自動生成，不夠詳細。如果有需要，可以通過注解自定義接口聲明。常用的注解包括：
/**
@Api：修飾整個類，描述Controller的作用
@ApiOperation：描述一個類的一個方法，或者說一個接口
@ApiParam：單個參數描述
@ApiModel：用對象來接收參數
@ApiProperty：用對象接收參數時，描述對象的一個字段
@ApiResponse：HTTP響應其中1個描述
@ApiResponses：HTTP響應整體描述
@ApiIgnore：使用該注解忽略這個API
@ApiError ：發生錯誤返回的信息
@ApiImplicitParam：一個請求參數
@ApiImplicitParams：多個請求參數
*/
示例：
@PostMapping("/people")
@ApiOperation(value = "保存人員信息")
@ApiResponses({
@ApiResponse(code = 0, message = "保存成功"),
@ApiResponse(code = 1, message = "保存失敗")
})
public FrontResult save(
@ApiParam(value = "保存參數", example = "")
@RequestBody People people) {
people.setBirthday(Timestamp.valueOf(LocalDateTime.now()));
return new FrontResult(FrontResult.SUCCEED, "保存成功", peopleDao.save(people));
}
@Data
@ApiModel(description = "人員信息保存請求對象")
public class People {
@ApiModelProperty(value = "人員編號")
private Long id;
@ApiModelProperty(value = "姓名", required = true,position = 1)
private String name;
@ApiModelProperty(value = "性別", required = true,position = 2)
private String sex;
@ApiModelProperty(value = "生日", required = true,position = 3)
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
private Timestamp birthday;
}
查看文檔：
四、美化一下
如果覺得用起來不太習慣，可以用Swagger-Bootstrap-UI 替換Swagger 默認的UI實現左右菜單風格的Swagger-UI ，讓其看起來更清晰明了。
1.添加依賴
<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
2.重啟項目
訪問 http://localhost:8080/doc.html ：
