Swagger2、Swagger3 配置交流

Swagger

swagger 是一个方便快捷的接口在线调试及文档生成工具，下面记录了swagger的配置过程

SpringBoot集成Swagger

1.新建一个Spring Boot项目，添加spring web (start)组件

2.导入相关依赖

在maven仓库中搜索 swagger2 和 swagger-ui 依赖，版本可选择下载次数最多的

<!-- 系统自动配置的 swagger-ui-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!--swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

3.配置Swagger

新建一个config包，创建 SwaggerConfig.java,用来配置Swagger有关的信息

使用 @Configuration 将此类添加至Bean，@EnableSwagger2 开启Swagger功能

@Configuration
@EnableSwagger2     //开启swagger
public class SwaggerConfig {	
}

4.启动项目测试，打开浏览器输入 localhost:8080/swagger-ui.html 转到swagger 界面

5.配置Swagger实例

Swagger有个自己的实例 Docket ，想要使用Swagger 只需要返回一个Docket的实例就可以。

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //配置Swagger实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    //配置apiInfo信息
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact =new Contact("jerry","localhost:1001/swagger-ui.html","123456@163.com");
        return new ApiInfo("jerryTest",
                "接口测试文档",
                "v1.0",
                "localhost",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
}

• 如果需要传token，则使用以下配置

@Bean
    public Docket docket(){
        //配置请求头
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("Authorization").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("qtec")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.qtec"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
    }

Swagger配置扫描接口

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.jerry.controller"))
	        //RequestHandlerSelectors，配置扫描接口的方式
								        // basePackage:指定要扫面的包 （通常使用的是这种方式）
								        // any() 全部扫描
								        // none () 不扫描
								        // withClassAnnotation 扫描类上的注解，参数是一个注解的反射对象
								        //withMethodAnnotation 扫描方法上的注解
        //path() 用来过滤什么路径
        .build();
}

配置API 文档的分组

分组的目的是为了协同开发，为了方便接口的责任归咎，特将接口开发文档进行分组，要实现分组只需在Docket中添加 groupName("") 字段就可以实现分组

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("jerry")
}

@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("tom")
}

搭配使用的注解

@ApiModel(“标注此类的作用”)

@ApiModelProperty(“标注此属性的含义”)

@ApiModel(value = "新增地址请求参数")
public class AddAddressRequest{
    @ApiModelProperty(value = "收件人")
    private String addressee;
    @ApiModelProperty(value = "联系方式")
    private String adTel;
}

============================================================

添加完group信息后完整代码

package com.jerry.swaggerstudy.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2     //开启swagger
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("jerry")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.jerry.swaggerstudy.controller"))
//                .paths(PathSelectors.ant("/jerry/*"))
                .build();
    }

    //配置接口信息
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("jerry", "http://test.com", "123@163.com");

        return new ApiInfo("Swagger Study"
                , "For Test"
                , "1.0"
                , "http://jerry.com/swagger-ui/for study"
                ,  contact
                , "Apache 2.0"
                , "http://www.apache.org/licenses/LICENSE-2.0"
                , new ArrayList<VendorExtension>());
    }
}

swagger3(更简洁的版本)

swagger3 是最近刚更新的一个本版，新版本的依赖如果使用与swagger2保持一致，则会显示以下页面：

其实swagger3 使得依赖更加简便了。只需要引用一个pom依赖，访问的链接也有所改动（它更加贴近现在主流的访问习惯RestFul风格）。

依赖如下：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

访问的链接变为
ip:port/swagger-ui/
例如：localhost:1001/swagger-ui/
页面如下所示：

• 其实我个人觉得两者之间除了颜面的配色有点变化之外，其他的还是保持一致的

欢迎各位大佬来批评指正，留下宝贵的意见！