swagger

介绍

• 号称世界上最流行的APi框架；
• restful Api文档在线自动生成工具 ->APi文档与Api定义同步更新
• 直接运行，可以在线测试APi接口
• 支持多种语言

官网：https://swagger.io/

为什么需要Swagger？

前后端分离，大量接口难以理解。可以自动化解决了人力编写接口文档的问题。

运行第一个swagger项目

1、创建springboot项目，导入web模块

2、引入swagger依赖

依赖

<!-- 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、创建controller层的hello

@Controller
public class Hello {
    @ResponseBody
    @RequestMapping("/hello")
    public String hello(){
        return "Hello World";
    }
}

4、编写配置类(配置全部默认)

@EnableSwagger2 // 开启swagger2
@Configuration //添加到配置里面
public class swaggerConfig {
    }

这时候，我们已经可以使用swagger了。

配置部门swagger页面

@EnableSwagger2 // 开启swagger2
@Configuration //添加到配置里面
public class swaggerConfig {

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

    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("szw", "https://www.baidu.com/", "1277524222@qq.com");

        return new ApiInfo(
                "szw的测试swagger案例",
                "沉下心来慢慢学",
                "1.0",
                "urn:tos",
                contact,//作者信息
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

配置完成后，我们可以打开http://localhost:8080/swagger-ui.html进行查看。

1585318827459.png

Swagger配置扫描接口

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2) //配置需要扫描的接口
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors，配置要扫描接口的方式
                //basePackage ，指定要扫描的包
                //any()扫描全部 none() 不扫描
                //withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.swagger.Controller"))
                .paths(PathSelectors.ant("/swagger/**"))
                .build();
    }

自定义配置是否启动

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2) //配置需要扫描的接口
                .apiInfo(apiInfo())
                .enable(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.Controller"))
                    .paths(PathSelectors.ant("/swagger/**"))
                    .build();
    }

可以根据项目环境自动更改swagger是否启动

 @Bean
    public Docket docket(Environment environment){
        //是指显示swagger的环境
        Profiles profiles = Profiles.of("dev","test");  //括号内可以写一个数组
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2) //配置需要扫描的接口
                .apiInfo(apiInfo())
                .enable(flag)   //这里进行判断
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.Controller"))
                .paths(PathSelectors.ant("/swagger/**"))
                .build();
    }

主配置文件

spring:
  profiles:
    active: dev # 这里进行更改

---
spring:
  profiles: dev
server:
  port: 8081

---
spring:
  profiles: dev2
server:
  port: 8082

配置多个Swagger分组

这里的分组，就是页面的右上角进行选择，这个功能可以很方便的看到一个团队的其他人写的api

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

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

Swagger的一些注释注解

@ApiModel("用户类")
public class User {
    @ApiModelProperty("用户名")
    public String userName;
    @ApiModelProperty("密码")
    public String password;
}

    @ApiOperation("作用域注解")
    @GetMapping("/use")
    public String use(){
        return "OK";
    }

@ApiModel("")，这个使用在类上

@ApiModelProperty("")使用在public的属性上

@ApiOperation("")作用域注解

Swagger文档页面进行测试

    @ApiOperation("测试")
    @GetMapping("/use")
    public String use(String userName){
        return "测试"+userName;
    }

测试页面

1585318876685.png

总结

1、我们可以通过Swagger给一些比较难理解的属性和接口，增加注释消息

2、接口文档实时更新

3、可以在线测试

需要注意：在项目发布的时候一定要关闭swagger，出于安全考虑，还可以减少运行的内存。