一文搞懂Swagger,让你明白用了Swagger的好处!!!

框架师

发布于 2020-06-16 16:20:37

3K2

发布于 2020-06-16 16:20:37

文章被收录于专栏：墨白的Java基地墨白的Java基地

前后端分离缺陷

了解Swagger之前,需要先知道什么是前后端分离

现在的时代
- SpringBoot + VUE
以前的时代
- SSM + JSP模板引擎====>后端程序员
前后端分离时代
- 通过相关的API接口进行交互
- 前后端相对独立,松耦合
- 前后端可以分别部署在不同的服务器上
- 伪造后端交互数据,json数据已经存在,不需要后端传入json数据了,前端工程已经可以运行
- 后端:后端控制层 + 服务层 + 数据访问层
- 前端:前端控制层 + 视图层
- 前后端如何交互?
但这样会产生新问题
- 前后端集成联调,前端和后端开发人员无法做到及时协商,尽早解决问题,就会导致项目延期
解决方案:
- 前端测试后端:postMan
- 后端提供接口,需要实时更新最新的消息和改动
- 首先指定schema[计划大纲],团队实时更新最新的API,可以降低集成的风险;
- 早些年:指定world计划文档
- 前后端分离:

Swagger简介

Swagger官网

号称世界上最流行的API框架
RestFul API文档在线生成工具--->>>==API文档与API同步更新==
可以直接运行,可以在线测试API接口
支持多种语言:(Java,PHP......)

官网界面

使用SpringBoot集成Swagger

创建SpringBoot-Web项目,导入相关依赖

注意事项:

在项目中使用Swagger需要SpringBox
swagger2
swaggerui


        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
            <version>2.9.2version>
        dependency>
        
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger-uiartifactId>
            <version>2.9.2version>
        dependency>

创建hello程序

扩展,一个hello程序有两个请求,一个是SpringBoot项目默认的/error

image-20200611133103333

@RestController
public class HelloController {
    /**
     * 测试Controller
     *
     * @return
     */
    @GetMapping("/hello")
    public String hello() {
        return "你好呀!!!Swagger";
    }
}

配置Swagger,新建SwaggerConfig

@Configuration // 标识配置类
@EnableSwagger2 // 开启Swagger
public class SwaggerConfig {
    
}

测试运行

唯一地址:http://localhost:8080/swagger-ui.html

首页信息

配置Swagger信息

修改SwaagerConfig

package com.mobai.swagger.config;

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

import java.util.ArrayList;

/**
 * Software：IntelliJ IDEA 2020.1 x64
 * Author: MoBai·杰
 * Date: 2020/6/11 13:33
 * ClassName:SwaggerConfig
 * 类描述：Swagger配置类
 */
@Configuration // 标识配置类
@EnableSwagger2 // 开启Swagger
public class SwaggerConfig {

    /**
     * 配置了Swagger的Docket的Bean实例
     *
     * @return
     */
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    /**
     * 配置Swagger信息
     *
     * @return
     */
    private ApiInfo apiInfo() {
        // 配置作者信息
        Contact contact = new Contact("墨白",
                "https://www.mobaijun.com",
                "mobaijun8@163.com");
        // 配置API文档标题
        return new ApiInfo("框架师Api",
                // API文档描述
                "Api Documentation",
                // API版本号
                "1.0",
                // 配置URL(公司官网/blog地址)
                "https://www.mobaijun.com",
                // 作者信息
                contact,
                // 以下内容默认即可
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

Swagger配置扫描接口

Docket.select();

在SawggerConfig配置类完善配置扫描接口的参数

 /**
  * 配置了Swagger的Docket的Bean实例
  *
  * @return
  */
 @Bean
 public Docket docket() {
     return new Docket(DocumentationType.SWAGGER_2)
             .apiInfo(apiInfo())
             // 配置扫描接口
             .select()
             /*
              *RequestHandlerSelectors,配置要扫描接口的方式
              * 参数说明:
              * basePackage:基于包扫描
              * class:基于类扫描
              * any():扫描全部
              * none():全部都不扫描
              * withMethodAnnotation:通过方法的注解扫描
              * // withMethodAnnotation(GetMapping.class))
              * withClassAnnotation:通过类的注解扫描
              */
             .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
             // .paths()过滤,不扫描哪些接口
             .paths(PathSelectors.any())
             .build();
 }

配置Swagger启动

/**
 * 配置了Swagger的Docket的Bean实例
 *
 * @return
 */
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            // 配置Swagger是否启动,默认:true
            .enable(false)
            // 配置扫描接口
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
            .paths(PathSelectors.any())
            .build();
}

小测试:如果有一个需求,需要你判断在生成环境中使用,在发布的时候不使用

开发思路
- 先判断.enable()是不是等于false
- 注入Enable(flag)
实现,添加application-dev.properties生产环境配置和application-pro.properties发布环境配置
默认application.properties环境配置添加

# 开启profiles.active监听,dev测试环境,pro发布环境
spring.profiles.active=dev

生产环境修改端口号

server.port=8081

发布环境修改端口号

server.port=8082

SwaggerConfig配置类判断当前环境

/**
 * 配置了Swagger的Docket的Bean实例
 *
 * @return
 */
@Bean
public Docket docket(Environment environment) {
    // 设置要显示的Swagger环境
    Profiles profiles = Profiles.of("dev", "test");
    // 通过environment.acceptsProfiles();判断自己是否在自己设定换的环境当中
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            // 监听自己设置的环境
            .enable(flag)
            // 配置扫描接口
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
            .paths(PathSelectors.any())
            .build();
}

配置API文档的分组

配置多个组,添加.groupName()

   /**
     * 配置了Swagger的Docket的Bean实例
     *
     * @return
     */
    @Bean
    public Docket docket(Environment environment) {
        // 设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev", "test");
        // 通过environment.acceptsProfiles();判断自己是否在自己设定换的环境当中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 配置分组
                .groupName("墨白小组")
                // 监听自己设置的环境
                .enable(flag)
                // 配置扫描接口
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
}

效果

image-20200611145705157

配置多个组

@Configuration // 标识配置类
@EnableSwagger2 // 开启Swagger
public class SwaggerConfig {

    /**
     * 添加A组
     * 每个组各司其职
     *
     * @return
     */
    @Bean
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("A");
    }

    /**
     * 添加B组
     *
     * @return
     */
    @Bean
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("B");
    }

    /**
     * 添加C组
     *
     * @return
     */
    @Bean
    public Docket docket3() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("C");
    }

    /**
     * 配置了Swagger的Docket的Bean实例
     *
     * @return
     */
    @Bean
    public Docket docket(Environment environment) {
        // 设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev", "test");
        // 通过environment.acceptsProfiles();判断自己是否在自己设定换的环境当中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 配置分组
                .groupName("墨白小组")
                // 监听自己设置的环境
                .enable(flag)
                // 配置扫描接口
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mobai.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

效果

image-20200611150302823

实体类配置

@ApiModel("用户实体类") // 添加注释
public class User {
    // 添加注释
    @ApiModelProperty("年龄")
    private Integer age;

    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("账号")
    private String username;

    @ApiModelProperty("密码")
    private String password;

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

效果

效果图

Swagger常用注解
- @ApiModel("注释"):实体类添加注释
- @ApiModelProperty("注释"):给实体类属性添加注释
- @ApiOperation("注释")给接口(Controller)方法添加注释,放在方法上
- @ApiParam("")给方法的参数添加注释
- @Api("")给类添加注释
controller

package com.mobai.swagger.controller;


import com.mobai.swagger.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * Software：IntelliJ IDEA 2020.1 x64
 * Author: MoBai·杰
 * Date: 2020/6/11 13:25
 * ClassName:HelloController
 * 类描述： 测试类
 */
@ApiOperation("")
@RestController
public class HelloController {
    /**
     * 测试Controller
     *
     * @return
     */
    @GetMapping("/hello")
    public String hello() {
        return "你好呀!!!Swagger";
    }

    /**
     * 只要我们的接口中,返回值存在实体类,Swagger就会扫描到
     *
     * @return
     */
    @PostMapping("/user")
    public User user() {
        return new User();
    }

    @ApiOperation("Post测试类")
    @PostMapping(value = "/post")
    public User post(@ApiParam("用户对象") User user) {
        return user;
    }
}

总结
- 添加@Configuration注解,标识配置类
- 添加@EnableSwagger2注解开启Swagger
- Swagger2
- Swagger-ui
- 创建SpringBoot项目,导入Swagger依赖
- 创建Swagger配置类
- 配置Swagger的Docket的Bean实例
- 配置Swagger信息
我们可以通过Swagger给一些比较难理解的属性或者接口,增加注释信息
接口文档实时更新
可以在线测试
Swagger是一个优秀的工具,几乎所有的大公司都在用
需要注意:正式发布的时候,关闭swagger!!!出于安全考虑,而且节省运行内存!