深度探索Swagger2：从介绍到多环境应用

引言

在当今互联网时代，RESTful API已经成为各种软件系统之间进行数据交换和通信的标准。而Swagger2作为一种RESTful API文档化工具，为开发者提供了便捷的方式来描述、调试和测试API。本文将深入探讨Swagger2的介绍、基本应用以及多环境应用，帮助读者更好地理解和应用Swagger2。

1. Swagger2

1.1 什么是Swagger2

Swagger2是一种用于设计、构建和文档化RESTful API的工具，它使用简单的注解来描述API的结构和功能。通过Swagger2，开发者可以轻松地生成交互式的API文档，并且可以直接在文档中进行API的调试和测试。

1.2 Swagger2的背景

Swagger最初是由Tony Tam在2010年创建的，旨在解决RESTful API的文档化和调试问题。随着RESTful API的普及，Swagger逐渐发展成为Swagger2，并成为了业界标准之一。

1.3 Swagger2的常用注解

注解	描述
@Api	将类标记为 Swagger 资源。
@ApiImplicitParam	表示 API 操作中的单个参数。
@ApiImplicitParams	允许多个 ApiImplicitParam 对象列表的包装器。
@ApiModel	提供有关 Swagger 模型的其他信息。
@ApiModelProperty	添加和操作模型属性的数据。
@ApiOperation	描述针对特定路径的操作或通常是 HTTP 方法。
@ApiParam	为操作参数添加额外的元数据。
@ApiResponse	描述操作的可能响应。
@ApiResponses	允许多个 ApiResponse 对象列表的包装器。
@Authorization	声明要在资源或操作上使用的授权方案。
@AuthorizationScope	描述 OAuth2 授权范围。

2. Swagger2基本应用

先来个小插曲，介绍两个响应类JsonResponseStatus，JsonResponseBody

package com.yuan.ttx.config;

//import io.swagger.annotations.ApiModel;
//import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
//@ApiModel("响应对象")
public class JsonResponseBody<T> {

//    @ApiModelProperty("响应码")
    private Integer code;
//    @ApiModelProperty("响应信息")
    private String msg;
//    @ApiModelProperty("响应数据")
    private T data;
//    @ApiModelProperty("响应条数(用于分页)")
    private Long total;

    private JsonResponseBody(JsonResponseStatus jsonResponseStatus, T data) {
        this.code = jsonResponseStatus.getCode();
        this.msg = jsonResponseStatus.getMsg();
        this.data = data;
    }

    private JsonResponseBody(JsonResponseStatus jsonResponseStatus, T data, Long total) {
        this.code = jsonResponseStatus.getCode();
        this.msg = jsonResponseStatus.getMsg();
        this.data = data;
        this.total = total;
    }

    public static <T> JsonResponseBody<T> success() {
        return new JsonResponseBody<T>(JsonResponseStatus.OK, null);
    }

    public static <T> JsonResponseBody<T> success(T data) {
        return new JsonResponseBody<T>(JsonResponseStatus.OK, data);
    }

    public static <T> JsonResponseBody<T> success(T data, Long total) {
        return new JsonResponseBody<T>(JsonResponseStatus.OK, data, total);
    }

    public static <T> JsonResponseBody<T> unknown() {
        return new JsonResponseBody<T>(JsonResponseStatus.UN_KNOWN, null);
    }

    public static <T> JsonResponseBody<T> other(JsonResponseStatus jsonResponseStatus) {
        return new JsonResponseBody<T>(jsonResponseStatus, null);
    }

}

package com.yuan.ttx.config;

import lombok.Getter;

@Getter
public enum JsonResponseStatus {

    OK(200, "OK"),
    UN_KNOWN(500, "未知错误"),
    RESULT_EMPTY(1000, "查询结果为空！"),
    ;

    private final Integer code;
    private final String msg;

    JsonResponseStatus(Integer code, String msg) {
        this.code = code;
        this.msg = msg;
    }

}

对相应类的使用

    @GetMapping("/list")
    public JsonResponseBody<List<Book>> list(){
        List<Book> list = iBookService.list();
        if(list.size()==0){
            return JsonResponseBody.other(JsonResponseStatus.RESULT_EMPTY);
        }
        return JsonResponseBody.success(list);
    }

    @PostMapping("/save")
    public JsonResponseBody<Boolean> save(Book book){
        boolean save = iBookService.save(book);
        return JsonResponseBody.success(save);
    }

现在正式进行swagger2的使用
导入swagger2需要的pom文件

  <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

在导入swagger2用到的类,需要把.apis(RequestHandlerSelectors.basePackage(“com.yuan.ttx”))括号内的路径改为自己文件夹的路径

package com.yuan.ttx.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
//@Profile({"dev", "test"})  dev(开发)、test(测试)、prod(生产)
public class Swagger2Configuration extends WebMvcConfigurationSupport {

    /**
     * 创建该API的基本信息  http://项目实际地址/doc.html
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot集成Swagger2")
                .description("测试系统")
                .termsOfServiceUrl("https://www.baidu.com")
                .version("1.0.0")
                .build();
    }

    /**
     * 创建API应用
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yuan.ttx"))
                .paths(PathSelectors.any())
                .build();
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

然后在端口路径后加上doc.html,回车，就出现这个,但swagger2原本不长这样，这是一个类似升级版

原来的是在路径后面添加/v2/api-docs

咯，就长这样。
然后需要用到一个测试工具，我的是Apifox软件,然后选择导入，选择swagger

提交之后再点击导入

这个时候就能进行一个测试了，但是没有中文说明，对测试人员和前端人员很不友好，所以需要进行添加备注
Conntroller类中添加**@Api(tags = “用于完成书籍操作的接口”)**

@RestController
@RequestMapping("/book")
@Api(tags = "用于完成书籍操作的接口")
public class BookController {

方法中添加@ApiOperation

 @ApiOperation(value = "实现书籍的全部查询")
    @GetMapping("/list")
    public JsonResponseBody<List<Book>> list(){
        List<Book> list = iBookService.list();
        if(list.size()==0){
            return JsonResponseBody.other(JsonResponseStatus.RESULT_EMPTY);
        }
        return JsonResponseBody.success(list);
    }

    @ApiOperation(value = "实现书籍的增加操作")
    @PostMapping("/save")
    public JsonResponseBody<Boolean> save(Book book){
        boolean save = iBookService.save(book);
        return JsonResponseBody.success(save);
    }

实体类中类上添加@ApiModel，属性上添加@ApiModelProperty,不展示用hidden隐藏，比如逻辑删除字段

Getter
@Setter
@Accessors(chain = true)
@TableName("t_book")
@ApiModel("商品对象")
public class Book implements Serializable {

    private static final long serialVersionUID = 1L;

    /**
     * 书本编号
     */
    @ApiModelProperty("商品编号")
    @TableId(value = "id", type = IdType.AUTO)
    private Long id;

    /**
     * 书本名称
     */
    @ApiModelProperty("商品名称")

    @TableField("bookname")
    private String bookname;

    /**
     * 书本价格
     */
    @ApiModelProperty("商品价格")

    @TableField("price")
    private Float price;

    /**
     * 书本类型
     */
    @ApiModelProperty("商品类型")
    @TableField("booktype")
    private String booktype;

    @ApiModelProperty(hidden = true)

    @TableField
    private int state;

    @ApiModelProperty(hidden = true)
    @Version
    private Integer version;

@ApiModel("响应对象")
public class JsonResponseBody<T> {

    @ApiModelProperty("响应码")
    private Integer code;
    @ApiModelProperty("响应信息")
    private String msg;
    @ApiModelProperty("响应数据")
    private T data;
    @ApiModelProperty("响应条数(用于分页)")
    private Long total;

设置好之后再打开http://localhost:8081/doc.htm，就有以下说明备注了

模糊查询的参数表明使用

 @ApiOperation(value = "实现书籍的全部查询")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name",value = "模糊查询的名称"),
            @ApiImplicitParam(name = "price",value = "模糊查询的价格")
    })
    @GetMapping("/listmh")
    public JsonResponseBody<List<Book>> listmh(String name,Double price){
        List<Book> list = iBookService.list();
        return JsonResponseBody.success(list);
    }

此时测试工具重新连接http://localhost:8081/v2/api-docs使用就会有说明注释了

3. Swagger2多环境应用

在Swagger2Configuration类上面添加

@Profile({"dev", "test"})

然后创建测试环境配置application-test.yml

server:
    port: 8082

然后创建开发环境配置application-dev.yml

server:
    port: 8083

然后去pom文件找到

<skip>true</skip>

把他删除掉，不删除掉项目打包运行跳过启动类，不能编译
然后package打包

打包完成后会有一个jar，把他c到桌面去
然后在终端运行

此刻运行的是8081，生产环境

此刻http://localhost:8081/doc.html是访问不到的
现在想访问，去把项目设置成开发环境,输入下面代码，回车


然后访问http://localhost:8083/doc.html就能进入swagger2调试了

总结

通过本文的介绍，读者可以全面了解Swagger2的介绍、基本应用以及多环境应用。Swagger2作为一种强大的RESTful API文档化工具，为开发者提供了便捷的方式来描述、调试和测试API，极大地提高了开发效率和API的可维护性。希望本文能够帮助读者更好地理解和应用Swagger2，从而在实际项目中发挥其价值。