springboot2.x集成swagger

集成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經常使用註解

1. @Api：用在類上，標誌此類是Swagger資源

   屬性名稱	備註
   value	該參數沒什麼意義，在UI界面上不顯示，因此不用配置
   tags	說明該類的做用，參數是個數組，能夠填多個
   description	對api資源的描述

2. @ApiOperation：用在方法上，描述方法的做用

   屬性名稱	備註
   value	方法的用途和做用
   tags	方法的標籤，能夠設置多個值
   notes	方法的注意事項和備註
   response	返回的類型（儘可能不寫，由swagger掃描生成）

3. @ApiImplicitParams：包裝器：包含多個ApiImplicitParam對象列表

   屬性名稱	備註
   value	多個ApiImplicitParam配置

4. @ApiParam：用於Controller中方法的參數說明

   屬性名稱	備註
   name	屬性名稱
   value	屬性值
   defaultValue	默認屬性值
   allowableValues	能夠不配置
   required	是否屬性必填
   allowMultiple	文件上傳時，是否容許多文件上傳

5. @ApiImplicitParam：定義在@ApiImplicitParams註解中，定義單個參數詳細信息，若是隻有一個參數，也能夠定義在方法上

   屬性名稱	備註
   name	參數名
   value	參數說明
   dataType	參數類型
   paramType	表示參數放在哪裏 header : 請求參數的獲取：@RequestHeader query : 請求參數的獲取：@RequestParam path : 請求參數的獲取：@PathVariable body : 不經常使用 form : 不經常使用
   defaultValue	參數的默認值
   required	參數是否必須傳

6. @ApiModel：用在類上，表示對類進行說明，用於實體類中的參數接收說明

   屬性名稱	備註
   value	默認爲類的名稱
   description	對該類的描述

7. @ApiModelProperty：在model類的屬性添加屬性說明

   屬性名稱	備註
   value	屬性描述
   name	屬性名稱
   allowableValues	參數容許的值
   dataType	數據類型
   required	是否必填

8. @ApiResponses：包裝器：包含多個ApiResponse對象列表

   屬性名稱	備註
   value	多個ApiResponse配置

9. @ApiResponse：定義在@ApiResponses註解中，通常用於描述一個錯誤的響應信息

   屬性名稱	備註
   code	響應碼
   message	狀態碼對應的響應信息
   response	默認響應類 Void
   responseContainer	參考ApiOperation中配置

10. @ApiIgnore()：用於類或者方法上，不被顯示在頁面上

總結

除上面以外有點值得注意的是，若是是上傳文件的話，須要把@ApiImplicitParam中的dataType屬性配置爲__File不然在swagger中會顯示爲文本框而不是上傳按鈕

若是須要項目代碼，能夠去個人github中下載；具體代碼能夠查看swagger目錄