SpringBoot 基礎Swagger增強版

Springboot 2 以上版 集成 swagger2

swagger自帶的ui挺弟弟的，網上看到了大佬寫的不錯.

增強版來源 https://doc.xiaominfo.com/guide/useful.html

1.依賴配置

 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
      <version>2.9.2</version>
</dependency>
<dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>swagger-bootstrap-ui</artifactId>
      <version>1.9.6</version>
</dependency>

注:如果和你的springboot 核心依賴衝突 導入以下依賴

<dependency>
   <groupId>org.springframework.plugin</groupId>
    <artifactId>spring-plugin-core</artifactId>
    <version>1.2.0.RELEASE</version>
</dependency>
<dependency>
    <groupId>org.springframework.plugin</groupId>
    <artifactId>spring-plugin-metadata</artifactId>
    <version>1.2.0.RELEASE</version>
</dependency>

2.配置config

其實配置 和swagger配置一模一樣，增強版本有些其他的 功能。

@Configuration
@EnableSwagger2
//使用增強功能
@EnableSwaggerBootstrapUI 
public class SwaggerConfig {

    /** 掃包根路徑 **/
    //默認業務代碼掃包路徑
    private final String defaultPackage = "com.xxxxx.xxx";
    private final String defaultGroupName = "業務代碼組";
    //自定義掃包路徑(我定義了一個系統級別代碼)
    private final String systemPackage= "com.xxxxx.xxx";
    private final String systemGroupName = "系統管理組";
    //標題
    private final String title = "xxxxx系統";
     //描述
    private final String description = "xxxxm描述";
    //termsOfServiceUrl
    private final String termsOfServiceUrl = "xxxxx";
    private final String version = "1.0";
    //消息體對象
    private final  String resp = "ResponseMsg";


    @Bean(value = "defaultApi")
    public Docket createRestApi() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName(defaultGroupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage(defaultPackage))
                .paths(PathSelectors.regex("/api.*"))
                .build();
        return buildDefaultApi(docket);
    }
    @Bean(value = "systemApi")
    public Docket systemApi() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName(systemGroupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage(systemPackage))
                .paths(PathSelectors.regex("/sys.*"))
                .build();
        return buildDefaultApi(docket);

    }

    /**
     * 默認配置
     * @param docket
     * @return
     */
    public Docket  buildDefaultApi(Docket docket){
        List<ResponseMessage> responseMessageList = new ArrayList<>();
        responseMessageList.add(new ResponseMessageBuilder().code(404).message("找不到資源").responseModel(new ModelRef(resp)).build());
        responseMessageList.add(new ResponseMessageBuilder().code(400).message("參數校驗異常").responseModel(new ModelRef(resp)).build());
        responseMessageList.add(new ResponseMessageBuilder().code(401).message("沒有登錄憑證/授權碼過期").responseModel(new ModelRef(resp)).build());
        responseMessageList.add(new ResponseMessageBuilder().code(500).message("服務器內部錯誤").responseModel(new ModelRef(resp)).build());
        responseMessageList.add(new ResponseMessageBuilder().code(402).message("無效權限").responseModel(new ModelRef(resp)).build());

        docket.apiInfo(apiInfo())
                .globalResponseMessage(RequestMethod.GET, responseMessageList)
                .globalResponseMessage(RequestMethod.POST, responseMessageList)
                .globalResponseMessage(RequestMethod.PUT, responseMessageList)
                .globalResponseMessage(RequestMethod.DELETE, responseMessageList)
                .securityContexts(Lists.newArrayList(securityContext())).securitySchemes(Lists.<SecurityScheme>newArrayList(apiKey()));
        return docket;
    }


    /**
     * 登錄auto配置
     * @return
     */
    private ApiKey apiKey() {
        return new ApiKey("BearerToken", "Authorization", "header");
    }

    private SecurityContext securityContext() {
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex("/.*"))
                .build();
    }
    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Lists.newArrayList(new SecurityReference("BearerToken", authorizationScopes));
    }

    /**
     * apiInfo 
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl(termsOfServiceUrl)
                .version(version)
                .contact("xxx")
                .build();
    }
}

這樣就配好了，如果系統做了權限配置 開放以下路徑白名單
 

/swagger-resources 
/v2/api-docs 
/v2/api-docs-ext 
/doc.html
/webjars/**

注：主頁地址 api地址爲 /doc.html 非 /swagger-ui.html

3.增強功能
 

3.1訪問權限控制

swagger.production=true

開啓生產環境,屏蔽Swagger所有資源接口,關閉皆可以訪問。

3.2訪問頁面加權控制
 

 

## 開啓Swagger的Basic認證功能,默認是false
swagger.basic.enable=true
## Basic認證用戶名
swagger.basic.username=admin
## Basic認證密碼
swagger.basic.password=admin.xxx

 

4.界面風格(建議直接看knife4j官網，我都是直接抄的）

 

我的欣賞水平覺得 比 原本ui好看。

參考資料地址 :
https://doc.xiaominfo.com