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