集成swagger
pom包配置
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
添加Swagger配置文件
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 創建一個Docket對象
* 調用select()方法，
* 生成ApiSelectorBuilder對象實例，該對象負責定義外漏的API入口
* 通過使用RequestHandlerSelectors和PathSelectors來提供Predicate，在此我們使用any()方法，將所有API都通過Swagger進行文檔管理
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//標題
.title("Spring Boot中使用Swagger2構建RESTful APIs")
//簡介
.description("")
//服務條款
.termsOfServiceUrl("")
//作者個人信息
.contact(new Contact("chenguoyu","","chenguoyu_sir@163.com"))
//版本
.version("1.0")
.build();
}
}
如果不想將所有的接口都通過swagger管理的話，可以將RequestHandlerSelectors.any()修改為RequestHandlerSelectors.basePackage()
配置靜態訪問資源
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
// 解決 swagger-ui.html 404報錯
registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
}
}
到這里為止swagger就已經配置完了，可以啟動項目，然后訪問如下鏈接即可http://localhost:9000/swagger...
端口號applicationContext中設置的端口號。
集成swagger-bootstrap-ui
由于個人感覺原生的swagger-ui不太好看，網上提供了swagger-bootstrap-ui。
pom依賴
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.3</version> </dependency>
配置靜態訪問資源
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
// 解決 swagger-ui.html 404報錯
registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
// 解決 doc.html 404 報錯
registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
}
}
這時只需要訪問以下鏈接即可http://localhost:9000/doc.html
swagger常用注解
@Api：用在類上，標志此類是Swagger資源
| 屬性名稱 | 備注 |
|---|---|
| value | 該參數沒什么意義，在UI界面上不顯示，所以不用配置 |
| tags | 說明該類的作用，參數是個數組，可以填多個 |
| description | 對api資源的描述 |
@ApiOperation：用在方法上，描述方法的作用
| 屬性名稱 | 備注 |
|---|---|
| value | 方法的用途和作用 |
| tags | 方法的標簽，可以設置多個值 |
| notes | 方法的注意事項和備注 |
| response | 返回的類型（盡量不寫，由swagger掃描生成） |
@ApiImplicitParams：包裝器：包含多個ApiImplicitParam對象列表
| 屬性名稱 | 備注 |
|---|---|
| value | 多個ApiImplicitParam配置 |
@ApiParam：用于Controller中方法的參數說明
| 屬性名稱 | 備注 |
|---|---|
| name | 屬性名稱 |
| value | 屬性值 |
| defaultValue | 默認屬性值 |
| allowableValues | 可以不配置 |
| required | 是否屬性必填 |
| allowMultiple | 文件上傳時，是否允許多文件上傳 |
@ApiImplicitParam：定義在@ApiImplicitParams注解中，定義單個參數詳細信息，如果只有一個參數，也可以定義在方法上
| 屬性名稱 | 備注 |
|---|---|
| name | 參數名 |
| value | 參數說明 |
| dataType | 參數類型 |
| paramType | 表示參數放在哪里 header : 請求參數的獲?。篅RequestHeader query : 請求參數的獲?。篅RequestParam path : 請求參數的獲?。篅PathVariable body : 不常用 form : 不常用 |
| defaultValue | 參數的默認值 |
| required | 參數是否必須傳 |
@ApiModel：用在類上，表示對類進行說明，用于實體類中的參數接收說明
| 屬性名稱 | 備注 |
|---|---|
| value | 默認為類的名稱 |
| description | 對該類的描述 |
@ApiModelProperty：在model類的屬性添加屬性說明
| 屬性名稱 | 備注 |
|---|---|
| value | 屬性描述 |
| name | 屬性名稱 |
| allowableValues | 參數允許的值 |
| dataType | 數據類型 |
| required | 是否必填 |
@ApiResponses：包裝器：包含多個ApiResponse對象列表
| 屬性名稱 | 備注 |
|---|---|
| value | 多個ApiResponse配置 |
@ApiResponse：定義在@ApiResponses注解中，一般用于描述一個錯誤的響應信息
| 屬性名稱 | 備注 |
|---|---|
| code | 響應碼 |
| message | 狀態碼對應的響應信息 |
| response | 默認響應類 Void |
| responseContainer | 參考ApiOperation中配置 |
@ApiIgnore()：用于類或者方法上，不被顯示在頁面上
總結
除上面之外有點值得注意的是，如果是上傳文件的話，需要把@ApiImplicitParam中的dataType屬性配置為__File否則在swagger中會顯示為文本框而不是上傳按鈕
如果需要項目代碼，可以去我的github中下載；具體代碼可以查看swagger目錄
以上就是本文的全部內容，希望對大家的學習有所幫助，也希望大家多多支持億速云。
免責聲明：本站發布的內容（圖片、視頻和文字）以原創、轉載和分享為主，文章觀點不代表本網站立場，如果涉及侵權請聯系站長郵箱：is@yisu.com進行舉報，并提供相關證據，一經查實，將立刻刪除涉嫌侵權內容。
