【Swagger2】：让API文档编写变得轻松愉悦的神奇工具
Welcome Huihui's Code World ! !
接下来看看由辉辉所写的关于Swagger2的相关操作吧
目录
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包
一. Swagger2是什么
Swagger2是一个用于生成、描述和调用RESTful风格的Web服务的框架。它的主要功能是将项目中所有（想要暴露的）接口展现在页面上，并且可以进行接口调用和测试的服务。此外，Swagger2还遵循了OpenAPI规范，这是Linux基金会的一个项目，旨在通过提供标准和工具来促进API的开放性和可发现性。
在日常开发中，编写和维护接口文档是每个程序员的职责。然而，随着项目的复杂度增加，接口文档的管理变得越来越困难。这时，Swagger2就可以发挥其强大的作用。它可以快速帮助我们编写最新的API接口文档，大大减少了会议前整理各种资料的时间，从而提升了团队开发的沟通效率。
在Spring框架中，我们可以使用@EnableSwagger2注解来开启Swagger2相关技术。它会扫描当前类所在包以及子包中所有类型的swagger相关注解，从而实现swagger文档的定制。
二.Swagger2有什么用
Swagger2的主要用途在于生成、描述和调用RESTful风格的Web服务。它可以让项目中所有（想要暴露的）接口展现在页面上，并且可以进行接口调用和测试的服务。在日常开发中，编写和维护接口文档是每个程序员的职责。然而，随着项目的复杂度增加，接口文档的管理变得越来越困难。这时，Swagger2就可以发挥其强大的作用。它可以快速帮助我们编写最新的API接口文档，大大减少了会议前整理各种资料的时间，从而提升了团队开发的沟通效率。
Swagger2还可以给一些比较难理解的属性或者接口增加注释信息，并提供接口文档实时更新的功能，可以在线测试。通过这些功能，我们可以更高效地理解和使用接口，提升工作效率。因此，Swagger2是一个优秀的工具，对于开发者来说具有很高的实用价值。
三.Swagger2怎么使用
1.导入依赖
io.springfox springfox-swagger2 2.9.2 com.github.xiaoymin swagger-bootstrap-ui 1.9.6 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) { QueryWrapperwrapper =new QueryWrapper<>(); wrapper.like("name",name); //简单的分页查询 Page page = new Page<>(1, 5); Page 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; /** ** *
* * @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<>(); }
五.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: dev3.使用maven package打包测试
4.打开jar包
这样的话，生产的环境下就不能够使用swagger2了
写在最后的话
我们可以使用接口测试工具，将swagger2中的访问接口信息的接口导入进去
好啦，今天的分享就到这了，希望能够帮到你呢！