【Swagger2】：让API文档编写变得轻松愉悦的神奇工具

        Swagger2是一个用于生成、描述和调用RESTful风格的Web服务的框架。它的主要功能是将项目中所有（想要暴露的）接口展现在页面上，并且可以进行接口调用和测试的服务。此外，Swagger2还遵循了OpenAPI规范，这是Linux基金会的一个项目，旨在通过提供标准和工具来促进API的开放性和可发现性。

        在日常开发中，编写和维护接口文档是每个程序员的职责。然而，随着项目的复杂度增加，接口文档的管理变得越来越困难。这时，Swagger2就可以发挥其强大的作用。它可以快速帮助我们编写最新的API接口文档，大大减少了会议前整理各种资料的时间，从而提升了团队开发的沟通效率。

        在Spring框架中，我们可以使用@EnableSwagger2注解来开启Swagger2相关技术。它会扫描当前类所在包以及子包中所有类型的swagger相关注解，从而实现swagger文档的定制。

二.Swagger2有什么用

Swagger2的主要用途在于生成、描述和调用RESTful风格的Web服务。它可以让项目中所有（想要暴露的）接口展现在页面上，并且可以进行接口调用和测试的服务。在日常开发中，编写和维护接口文档是每个程序员的职责。然而，随着项目的复杂度增加，接口文档的管理变得越来越困难。这时，Swagger2就可以发挥其强大的作用。它可以快速帮助我们编写最新的API接口文档，大大减少了会议前整理各种资料的时间，从而提升了团队开发的沟通效率。

Swagger2还可以给一些比较难理解的属性或者接口增加注释信息，并提供接口文档实时更新的功能，可以在线测试。通过这些功能，我们可以更高效地理解和使用接口，提升工作效率。因此，Swagger2是一个优秀的工具，对于开发者来说具有很高的实用价值。

三.Swagger2怎么使用

1.导入依赖

<!-- Swagger UI，API文档生成工具 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
<!-- Swagger UI Bootstrap，美化API文档 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

2.创建Swagger配置类

package com.wh.springboot.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.wh.springboot.controller"))
                .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/");
    }

}

3.使用

根据接口路径查询接口信息

四.Swagger2的常用注解

1.@Api

@Api注解用在类上，说明该类的作用。可以标记一个Controller类做为swagger文档资源。

属性说明
value url的路径值
tags 如果设置这个值、value的值会被覆盖
produces 返回的格式类型例如："application/json, application/xml"
consumes 接收请求参数的类型例如："application/json, application/xml"
protocols Possible values: http, https, ws, wss.
authorizations 高级特性认证时配置

案例演示
@RestController
@RequestMapping("/oa-user")
@Api(tags = "用来完成用户操作的接口")
public class OaUserController {
    @Autowired
    private IOaUserService oaUserService;
    }
2.@ApiOperation

@ApiOperation注解用在方法上，说明方法的作用，每一个url资源的定义。

属性说明
value url的路径值
tags 如果设置这个值、value的值会被覆盖
produces 返回的格式类型例如："application/json, application/xml"
consumes 接收请求参数的类型例如："application/json, application/xml"
hidden 是否在文档中显示
notes 注释说明
response 返回的对象
responseContainer 这些对象是有效的 "List", "Set" or "Map".，其他无效
responseReference 指定对响应类型的引用。指定的引用可以是本地的，也可以是远程的*将按原样使用，并覆盖任何指定的response()类
responseHeaders 响应旁边提供的可能标题列表
httpMethod "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
code http的状态码默认 200

案例演示
    @ApiOperation(value = "完成用户的查询")
    @RequestMapping("/list")
    public Object list(String name) {
        QueryWrapper<OaUser> wrapper =new QueryWrapper<>();
        wrapper.like("name",name);
        //简单的分页查询
        Page<OaUser> page = new Page<>(1, 5);
        Page<OaUser> res = oaUserService.page(page, wrapper);
        res.getTotal();//数据总数
        res.getPages();//数据总页数
        return res.getRecords();
    }
3.@ApiImplicitParam

@ApilmplicitParam 注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入；

属性说明
paramType 参数放在哪个地方
name 参数名称
value 参数代表的含义
dataType 参数类型
dataTypeClass 参数类型
required 是否必要
defaultValue 参数的默认值

paramType

类型作用
path 以地址的形式提交数据，用于restful接口。请求参数采用@PathVariable获取
query 直接跟参数完成自动映射赋值。请求参数可采用@RequestParam获取
body 以流的形式提交，仅支持POST。请求参数采用@RequestBody获取
header 参数在request headers里边提交。请求参数采用@RequestHeader获取
form 以form表单的形式提交，仅支持POST。

案例演示
/**
     * 增加
     * @param oaUser
     * @return
     */
    @ApiImplicitParam(name="oaUser",value="新增传进来的用户对象")
    @RequestMapping("/add")
    public Map add(OaUser oaUser){
        oaUserService.save(oaUser);
        Map map = new HashMap();
        map.put("coed",200);
        map.put("msg","添加成功");
        return map ;
    }
3.@ApiImplicitParams

@ApilmplicitParams 如果有多个参数，则需要使用多个 @ApilmplicitParam 注解来描述，多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中；

案例演示
@ApiOperation(value = "新增书本信息", notes = "新增书本信息"
            ,produces = "application/json",consumes = "application/json")
@ApiImplicitParams({
            @ApiImplicitParam(name="bookname",value="书本名称",required = true,dataType = "String"),
            @ApiImplicitParam(name="price",value="书本价格",required = true,dataType = "Double"),
            @ApiImplicitParam(name="booktype",value="书本类型",required = true,dataType = "String")
})
@PostMapping("/addBook")
public JsonResponseBody<?> addBook(@RequestParam String bookname,
                                   @RequestParam Double price,
                                   @RequestParam String booktype){
    return bookService.insert(Book.builder()
        .bookid(UUID.randomUUID().toString().replace("-",""))
        .bookname(bookname)
        .booktype(booktype)
        .price(price)
        .build());
}
4.@ApiModel和@ApiModelProperty

@ApiModel注解描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用 @ApiImplicitParam注解进行描述的时候；

@ApiModelProperty注解描述一个model的属性。

属性说明
value 字段说明
name 参数名称
dataType 参数类型
hidden 在文档中隐藏
required 是否必要
example 举例说明
notes 注释说明

案例演示
package com.wh.springboot.model;

import com.baomidou.mybatisplus.annotation.*;

import java.io.Serializable;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;
import lombok.experimental.Accessors;

/**
 * <p>
 * 
 * </p>
 *
 * @author wh
 * @since 2023-12-16
 */
@Getter
@Setter
@Accessors(chain = true)
@TableName("t_oa_user")
@ApiModel(value = "用户对象")
public class OaUser implements Serializable {

    private static final long serialVersionUID = 1L;

    @TableId(value = "id", type = IdType.AUTO)
    @ApiModelProperty(value="用户编号")
    private Long id;

    /**
     * 用户名: 唯一键 登陆时使用 禁止修改
     */
    @TableField("name")
    @ApiModelProperty(value="用户名")
    private String name;

    /**
     * 用户密码：长度6~10位，MD5加密
     */
    @TableField("pwd")
    @ApiModelProperty(value="用户密码")
    private String pwd;

    /**
     * 用户角色：1 管理员 2 发起者 3 审批者 4 参与者 5 会议室管理员
     */
    @TableField("rid")
    @ApiModelProperty(value="用户角色")
    private Long rid;

    /**
     * 登录名
     */
    @TableField("loginName")
    @ApiModelProperty(value="登录名")
    private String loginName;

    /**
     * 乐观锁
     */
    @Version
    @ApiModelProperty(hidden = true)
    private Integer version;

    /**
     * 逻辑删除
     */
    @TableField("deleted")
    @ApiModelProperty(hidden = true)
    private Integer deleted;


}
注意：在这里可以不使用@ApiImplicitParam标注Swagger中的参数信息，因为在这里的输入参数是实体对象，而在实体对象中已经使用@ApiModel和@ApiModelProperty注解进行了标识。

5.@ApiParam

作用在方法的参数上，用来描述接口的参数信息(一个参设置一个)

@ApiParam必须与@RequestParam、@PathVariable和@RequestHeader一起使用。

属性说明
name 参数名称
value 参数简单描述
defaultValue 描述参数默认值
required 是否为必传参数, false:非必传; true:必传
allowMultiple 指定参数是否可以通过多次出现来接收多个值
hidden 隐藏参数列表中的参数
example 非请求体(body)类型的单个参数示例
examples @Example(value = @ExampleProperty(mediaType = “”, value = “”)) 参数示例，仅适用于请求体类型的请求

案例演示
@ApiOperation(value="新增书本信息1",notes="新增书本信息1")
@PostMapping("/addBooks")
public JsonResponseBody<?> addBooks(
            @ApiParam(name="bookName",value="bookName",required = true) @RequestParam("bookName") String bookName,
            @ApiParam(name="price",value="price",required = true) @RequestParam("price") float price,
            @ApiParam(name="bookType",value="bookType",required = true) @RequestParam("bookType") String bookType){
      System.out.println("bookName="+bookName+",price="+price+",bookType="+bookType);
    return new JsonResponseBody<>();
}

属性	说明
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
produces	返回的格式类型例如："application/json, application/xml"
consumes	接收请求参数的类型例如："application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置

属性	说明
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
produces	返回的格式类型例如："application/json, application/xml"
consumes	接收请求参数的类型例如："application/json, application/xml"
hidden	是否在文档中显示
notes	注释说明
response	返回的对象
responseContainer	这些对象是有效的 "List", "Set" or "Map".，其他无效
responseReference	指定对响应类型的引用。指定的引用可以是本地的，也可以是远程的*将按原样使用，并覆盖任何指定的response()类
responseHeaders	响应旁边提供的可能标题列表
httpMethod	"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
code	http的状态码默认 200

属性	说明
paramType	参数放在哪个地方
name	参数名称
value	参数代表的含义
dataType	参数类型
dataTypeClass	参数类型
required	是否必要
defaultValue	参数的默认值

类型	作用
path	以地址的形式提交数据，用于restful接口。请求参数采用@PathVariable获取
query	直接跟参数完成自动映射赋值。请求参数可采用@RequestParam获取
body	以流的形式提交，仅支持POST。请求参数采用@RequestBody获取
header	参数在request headers里边提交。请求参数采用@RequestHeader获取
form	以form表单的形式提交，仅支持POST。

属性	说明
value	字段说明
name	参数名称
dataType	参数类型
hidden	在文档中隐藏
required	是否必要
example	举例说明
notes	注释说明

属性	说明
name	参数名称
value	参数简单描述
defaultValue	描述参数默认值
required	是否为必传参数, false:非必传; true:必传
allowMultiple	指定参数是否可以通过多次出现来接收多个值
hidden	隐藏参数列表中的参数
example	非请求体(body)类型的单个参数示例
examples	@Example(value = @ExampleProperty(mediaType = “”, value = “”)) 参数示例，仅适用于请求体类型的请求

五.Swagger2在不同环境下的状态

为了保证接口文档的安全，禁用了生产环境的加载，具体说明请看：

参考地址：生产环境中禁用swagger - 简书

一般生产环境是不能放开swagger的，这样接口暴露在外网很不安全!!!

1.修改Swagger2配置类

添加@Profile注解，指明在何种环境下可以使用Swagger2，一般情况下只有在开发(dev)和测试(test)环境下才可以使用Swagger2；而在生产(dev)环境下不能使用Swagger2。

package com.wh.springboot.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.wh.springboot.controller"))
                .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/");
    }

}

2.修改application.yml

修改application.yml文件，配置项目系统的运行环境（dev/test/prod）

spring:
  #配置swagger2生产和测试环境不可用
  profiles:
    active: dev

3.使用maven package打包测试

4.打开jar包

这样的话，生产的环境下就不能够使用swagger2了

写在最后的话

我们可以使用接口测试工具，将swagger2中的访问接口信息的接口导入进去

好啦，今天的分享就到这了，希望能够帮到你呢！😊😊

【Swagger2】：让API文档编写变得轻松愉悦的神奇工具

🥳🥳Welcome Huihui's Code World ! !🥳🥳

一. Swagger2是什么

二.Swagger2有什么用

三.Swagger2怎么使用

1.导入依赖

2.创建Swagger配置类

3.使用

四.Swagger2的常用注解

1.@Api

2.@ApiOperation

3.@ApiImplicitParam

3.@ApiImplicitParams

4.@ApiModel和@ApiModelProperty

5.@ApiParam

五.Swagger2在不同环境下的状态

1.修改Swagger2配置类

2.修改application.yml

3.使用maven package打包测试

4.打开jar包

悦读