本文正在参加「Java主题月 - Java Debug笔记活动」，详情查看<活动链接>

前言

• 你是不是还在纠结和前端的调试过程中。调试完全靠口述这就尴尬了

问题场景

• 刚工作那会我们前后端调试就是两个人坐在一起你一句我一句逐个对字段。这样的你是不是经历过。
• 后来稍微升级了下，要求我们后端提供文档前端根据文档进行开发。但是还是有问题。前端有时候对后端的描述还是不清楚。有的时候甚至理解错

swagger

• 但是，现在我们有了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的页面就行了。这里只是提供思路。不具体实现(懒)