【RestFul接口文档】- 关于Swagger接口文档的使用说明

Swagger

1.Swagger简介

• 号称世界上最流行的API框架
• RESTful 文档自动生成工具 =>API文档和API定义同步进行
• 直接运行可测试API接口
• 支持多种语言（java，。。）

Swagger在项目中的使用需要springbox

• swagger
• ui

2.Springboot集成Swagger

1.新建Springboot项目
2.导入相关依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

3.编写Hello项目
4.开启Swagger支持 =>Config

@Configuration
@EnableSwagger2 //开启Swagger支持
public class SwaggerConfig {
}

5.测试运行http://localhost:8000/swagger-ui.html

3.Swagger的配置

1.注入Swagger的bean

@Configuration
@EnableSwagger2 //开启Swagger支持
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2);
    }
}

Swagger中有许多信息都是默认的，我们可以修改

2.修改Swagger的ApiInfo信息

可以看到在Docket中第一个赋值的就是这个属性。

可以通过new出来的Docket对象直接设置

Swagger的ApiInfo的配置

@Configuration
@EnableSwagger2 //开启Swagger支持
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //修改Swagger的ApiInfo信息
    private ApiInfo apiInfo(){
        return new ApiInfo(
                "wf的API文档",//标题
                "学习Swagger的开发API文档",//APi文档的描述
                "v1.0",
                "https://blog.csdn.net/gyhdxwang",//开发的组织
                new Contact("wf", "https://blog.csdn.net/gyhdxwang", "wangfeng614@163.com"),//开发者信息
                "Apache 2.0",//默认开源协议
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());

    }
}

3.运行测试

可以看到Swagger已经变成我们修改的内容；

4.Swagger配置扫描接口

可以看到Swagger默认扫描所有的接口。如果我们想让Swagger只扫描特定的端口，可以使用以下方法；

Swagger的接口扫描是通过select来build的。而其扫描有两种方式：

• apis：要扫描哪些路径
• paths：不要扫描哪些路径

Swagger的apis扫描方式

apis的扫描是通过一个叫RequestHandlerSelectors类来进行配置，该类有5种扫描的方式。

• basePackage
  
  可以看到在配置扫描的包后，其他非该包下的内容就不会被扫描出来
  

• any和none：就是全部扫描，和全部不扫描
  

• withClassAnnotation:扫描类上注解，注解的类（反射对象）
  扫描带有特定注解的类
  

• withMethodAnnotation：扫描接口上的注解
  扫描带有特定注解的方法
  

Swagger的apis方式最常用的方式是basePackage的方式

Swagger的paths的不扫描方式

该方式是提高PathSelectors选择器来实现，有4种方式

• ant：过滤特定包下的内容
  
  过滤的结果
  
• regex：字符匹配

关于Swagger扫描的代码：

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors:配置要扫描接口的方法
            //basePackage:通过包名来扫描
            //any:全部扫描
            //none:都不扫描
            //withClassAnnotation:扫描类上注解，注解的类（反射对象）
            //withMethodAnnotation:扫描接口上的注解
            .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
            //paths:设置过滤的路径
            //PathSelectors:配置扫描的方式
            .paths(PathSelectors.ant("/wf/**"))
            .build()//这是一个工厂模式
            ;
}

5.配置Swagger是否启动

该功能是通过Docket类的Enabled属性实现

如何在config中配置

• true表示开启
• false表示不开启
  

当Enabled配置为false时


不能扫描

关于是否开启Swagger的代码

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("wf.start.swaggerdemo.controller"))
                .build()//这是一个工厂模式
                ;
    }

问题如何配置Swagger在生产环境使用，发布时不使用

先配置环境，激活dev，dev端口是8001，pro端口是8002

我们对Docket进行配置

    @Bean
    public Docket docket(Environment environment){

        //获取项目的环境
        //1.先在方法添加Environment参数import org.springframework.core.env.Environment;
        //2.获取要显示Swagger的环境
        //of方法接收一个可变String参数
        Profiles profiles = Profiles.of("dev");
        //通过environment.acceptsProfiles判断是否在自己设定的环境
        boolean flag = environment.acceptsProfiles(profiles);


        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("wf.start.swaggerdemo.controller"))
                .build()//这是一个工厂模式
                ;
    }

先参数dev开发环境，

可以访问成功（注意dev环境配置的端口是8001，所以要访问8001的swagger-ui）

对pro环境进行测试


在开发环境下不显示。配置成功

6.配置API文档的分组

注意：此时关闭5中的多个环境，只使用最开始的8000端口（在application.properties中配置）

swagger中的分组是通过

.groupName("wf")

实现的。
例如：

    @Bean
    public Docket docket(Environment environment){

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("wf")
                .select()
                .apis(RequestHandlerSelectors.basePackage("wf.start.swaggerdemo.controller"))
                .build()//这是一个工厂模式
                ;
    }

运行截图

而分组依赖于Docket实例存在，如果想要配置多个分组,配置多个Swagger的bean即可。

配置多个分组：

 @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("A");
    }

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

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("C");
    }

运行结果


Swagger的分组配置成功！

7.对文档的具体配置

实体类配置

编写一个配置类

package wf.start.swaggerdemo.entity;

/**
 * @Description TODO
 * @Author gyhdx
 * @Date 2020/6/2 9:04
 */

public class User {

    public String userName;
    public String password;

    public User() {
    }

    public User(String userName, String password) {
        this.userName = userName;
        this.password = password;
    }
}

如果想要在Swagger的最下面的modle中显示该实体类，只需要在接口中返回该实体类即可

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

    //只要我们的Controller接口的返回之中存在实体类就会在Swagger的modle中显示
    @GetMapping("/userTest")
    public User getTest(){
        return new User("wf","1234");
    }
}

给实体类添加注释

我们上面虽然可以正常显示实体类，但是如果实体类中的参数过多我们可能就不知道，实体类中的具体参数的意思，此时我们需要给实体类添加注释

给实体类添加注解只需要两个参数；

• @ApiModel：用于注解实体类
• @ApiModelProperty：用于给实体类中的参数添加注解

@ApiModel("这是user的实体类")
public class User {

    @ApiModelProperty("用户名")
    public String userName;
    @ApiModelProperty("密码")
    public String password;

    public User() {
    }

    public User(String userName, String password) {
        this.userName = userName;
        this.password = password;
    }
}

运行结果

对controller接口添加注解

给controller接口添加注解主要是用来一下两个注解：

• @ApiOperation：这是给接口添加注解
• @ApiParam：给接口中的参数添加注解
  • 注意：在给参数添加注解时，如果接口参数是一个实体类，则Swagger会显示实体类的注解，不会显示我们配置的

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

    //只要我们的Controller接口的返回之中存在实体类就会在Swagger的modle中显示
    @GetMapping("/userTest")
    public User getTest(){
        return new User("wf","1234");
    }

    @ApiOperation("get测试接口")
    @GetMapping("/getTest")
    public User getTest2(@ApiParam("这是用户名") String userName){
        return new User("wf","1234");
    }

    @ApiOperation("post测试接口")
    @PostMapping("/postt")
    public User gett(@ApiParam("用户信息") User user){
        return user;
    }
}

运行结果：

4.在Swagger-ui中进行接口的测试

在Swagger显示的接口中有一个try it out按钮，该按钮就会开启测试界面，点击该按钮

出现Execute点击

会把返回体和，返回头的内容添加。

对于post请求也一样

不过不知道为什么，我的post测试时它使用get的方式进行测试，而进行get带参数测试时swagger使用post方式请求。不知道哪位大神能解决我的这个问题

5.总结

• 1.可以使用Swagger给一些比较难以理解的接口或属性添加注释
• 2.swagger产生的接口文档会实时更新
• 3.可以在线测试（虽然我的接口测试存在问题）

Swagger是一个优秀的工具，几乎所有大公司都有使用它
[注意点]：在正式发布的时候,关闭Swagger! ! !出于安全考虑。而且节省运行的内存;