springboot整合swagger。完爆前後端除錯

web介面開發時在除錯階段最麻煩的就是引數除錯，前端需要諮詢後端。後端有時候自己也不是很瞭解。這時候就會造成除錯一次介面就需要看一次程式碼。Swagger幫我們解決對接的麻煩

springboot接入swagger

• springboot 引入swagger只需要引入jar包，然後配置swagger啟動。並配合swagger的註解使用就可以實現文件自動生成了。我們先來看看效果

環境準備

• 程式碼還是基於spring倉庫開發。分支為feature/0004/springboot-swagger

• swagger.version=2.9.2

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

配置

@Configuration
@EnableSwagger2
public class SwaggerConfig2 {
    @Bean
    public Docket createRestApi() {

        // 新增請求引數，我們這裡把token作為請求頭部引數傳入後端
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        List<Parameter> parameters = new ArrayList<Parameter>();
        parameterBuilder.name("token").description("令牌")
                .modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        parameters.add(parameterBuilder.build());

        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com"))
                .paths(Predicates.not(PathSelectors.regex("/error.*")))
                .build().apiInfo(new ApiInfoBuilder()
                        .title("後端服務說明")
                        .description("SpringBoot整合Swagger，詳細資訊......")
                        .version("1.0")
                        .contact(new Contact("zxhtom", "zxhtom.blog.csdn.net", "870775401@qq.com"))
                        .license("The Apache License")
                        .licenseUrl("http://zxhtom.gitee.io")
                        .build())
                .useDefaultResponseMessages(false)
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts())
                .globalOperationParameters(parameters);
    }


    private List<ApiKey> securitySchemes() {
        List<ApiKey> apiKeyList = new ArrayList();
        apiKeyList.add(new ApiKey("Authorization", "token", "header"));
        return apiKeyList;
    }

    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build());
        return securityContexts;
    }

    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }
}

新增請求頭

securitySchemes(securitySchemes())
securityContexts(securityContexts())

• 在上面的兩端配置就是加入全域性的token設定的。在swagger-ui介面顯示是右上角有一把鎖的標誌

介面使用

註解使用

註解	功能
@Api()	用在請求的類上。表示該類的請求類用於文件標註
@ApiOperation()	用於方法上。對一個http請求的具體說明，出參入參說明
@ApiModel()	對請求實體的一個說明
@ApiModelProperty	對實體內屬性說明，也可以設定預設值
@ApiImpliciParams()	用於請求的方法上，裡面是ApiImpliciParam陣列
@ApiImpliciParam()	表示單獨請求引數。可以設定form表單中引數單獨設定
@ApiParam()	對請求方法中引數的單獨設定 類似ApiImpliciParam
@ApiResponses()	對請求方法上根據響應碼設定說明
@ApiResponse	單個響應碼說明
@ApiIgnore()	對該請求的忽略

• 具體使用可以檢視原始碼。原始碼上面有給出。

自定義swaggerUI

• 這裡需要首先介紹下spring資源的載入順序。

src/main/resources/META-INF/resources
src/main/resources/static
src/main/resources/public

• 這三個優先順序依次降低。歡句話說spring首先會在src/main/resources/META-INF/resources下尋找資源。所以這也是我們自定義swaggerUI的策略。我們只需要在META-INF下重新繪畫swaggerUI的頁面就行了。這裡只是提供思路。不具體實現(懶)

加入戰隊

# 加入戰隊

微信公眾號