Swagger入门

Swagger入门

一、什么是Swagger

在实际开发前后端分离项目的过程中，不知道大家有没有这种经历。

前端程序员小李：小王，我掉你接口咋报错了！你这水平是不是不行啊！

后端程序员小王：谁说啦！一看我这写了好久嘞！你才有错呢！

前端程序员小李：你不信你看！你这多了一个属性啊！

小王：您没看接口文档吧！您这都几百年之前的接口文档了！老板早就让我改了你那版了。

小李：敢怒不敢言…加班吧…

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。

所以说Swagger就这么一个东西，用来解决接口文档中可能遇到的一些问题。

二、SpringBoot集成Swagger

我们首先创建一个springboot项目，然后导入两个依赖。

<!-- 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>

之后我们创建一个很基本的helloController

package com.dll.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {
    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }
}

测一下！

It’s ok!

之后我们配置一下swagger。

创建一个swagger-config，里面将他配置到spring容器中。

package com.dll.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

}

重启下，我们在项目中来输入一个swagger-ui.html

swagger框被我们分成了以下部分！

三、Swagger配置

1、Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

我们来创建一个Docket实例，并把它注册到容器中。

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

Docket中有一个Apiinfo属性可以配置相关信息，我们这里定制一下。

ApiInfo中有一些我们可以自定义的信息。

这里我们再写一个配置apiInfo的实例。

    @Bean
    public ApiInfo apiInfo(){
        return new ApiInfo(
                "丽丽的swagger配置",
                "我的接口文档",
                "1.0",
                "https://www.bilibili.com/",
                new Contact("zjj","https://www.cueb.edu.cn","s747296681@vip.qq.com"),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

最后改一下上面Docket中的apiInfo。

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

四、配置扫描接口

OK，我们刚才是把项目中所有的接口都扫描了一手。但是假如我只想扫描一小点可不可！
当然可！

构建Docket时可以通过通过select()方法配置怎么扫描接口。

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
        .apis(RequestHandlerSelectors.basePackage("com.dll.controller"))//只扫描com.dll.controller包下的接口，很好理解！
        .build();
}

当然除了通过包扫描，RequestHandlerSelectors里面还提供一些其他扫描的方法。

any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口

4、除此之外，我们还可以配置接口扫描过滤：、

 public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select().apis(RequestHandlerSelectors.basePackage("com.dll.controller"))
                .paths(PathSelectors.ant("/zjj/**")).//只扫描zjj开头的接口
                        build();
    }

这里也有一些其他方法

any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制

这次配置完应该啥也访问不了了！因为我们没有zjj开头的接口啊！

果然！

五、配置swagger开关

通过enable可以配置swagger开关！

public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .enable(false)//true为开启，false为关闭
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.dll.controller")).
//                .paths(PathSelectors.ant("/zjj/**")).//只扫描zjj开头的接口
        
                        build();
    }

我们在这里将swagger的开关关闭。

发现无法访问了。

在开发中，我们的项目有很多环境，比如说生产环境啊，测试环境啊，那我们能不能动态的判断他是在什么环境中，并且根据环境来判断他到底开不开启swagger嘞？

当然可。

首先我们将相关环境配置一下，

这里我们创建，dev，test以及prod三种环境，对应端口号为8081，8082，8083

之后我们再配置文件中定义当前为dev环境。

OK，那我们如何获取当前是啥环境嘞？

我们可以通过environment对象来拿。

    @Bean
    public Docket docket(Environment environment){
        //设置一下可以访问的环境
        Profiles of = Profiles.of("dev", "test");
        //判断是不是在of中的test或者dev环境中，若在则返回true，不在返回false
        boolean b = environment.acceptsProfiles(of);

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .enable(b)//true为开启，false为关闭
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.dll.controller"))
                .build();
    }

这时候我们访问8081的dev环境，是完全可以进去的！

而8083的prod环境不可。

六、配置Api分组

在docket中可以配置groupName属性来设置分组。

.groupName("zjj")

那我们如何配置多个分组呢？或者说在多人开发的时候如何让每个人有一个单独的分组嘞？

我们只需要多配置一些Docket就可。

这里我们多配置4个docket。

    @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");
    }
    @Bean
    public Docket docket4(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("D");
    }

看一下，发现确实多了4个组。

七、实体配置

swagger中不止可以查看接口的信息，我们也可以查看各个实体类的信息。

首先定义用户实体类。

package com.dll.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiParam;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import org.springframework.context.annotation.Bean;

@Data
@AllArgsConstructor
@NoArgsConstructor

//类注释
@ApiModel("用户实体类")
public class User {
    //参数注释
    @ApiModelProperty("用户名")
    private String userName;
    @ApiModelProperty("密码")
    private String pwd;
}

然后记得要在一个controller返回相关的对象哈！

package com.dll.controller;

import com.dll.pojo.User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {
    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }
    @GetMapping("/user1")
    public User user(){
        return new User("张峻杰","789");
    }
}

之后我们就可以在swagger中康到了！

常用的注解。

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty

八、接口测试

我们可以在swagger-ui中进行接口的测试.

点击接口右上角的tryItOut就可以了

我们测一下我们上面写的user1方法。

OK没有问题！

九、自定义UI

bootstrap-ui

我们可以导入不同的包实现不同的皮肤定义：

1、默认的 访问 http://localhost:8080/swagger-ui.html

<dependency> 



    <groupId>io.springfox</groupId>



    <artifactId>springfox-swagger-ui</artifactId>



    <version>2.9.2</version>



</dependency>

2、bootstrap-ui 访问 http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->



<dependency>



    <groupId>com.github.xiaoymin</groupId>



    <artifactId>swagger-bootstrap-ui</artifactId>



    <version>1.9.1</version>



</dependency>

3、mg-ui 访问 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->



<dependency>



    <groupId>com.zyplayer</groupId>



    <artifactId>swagger-mg-ui</artifactId>



    <version>1.0.6</version>



</dependency>