第二章：Swagger2

目录

背景介绍

什么是Swagger2

常用注解

SpringBoot整合Swagger2

生产环境下屏蔽Swagger2

修改Swagger2配置类

修改application.yml

使用maven package打包测试

运行测试

背景介绍

在团队开发中，一个好的 api 文档不但可以减少大量的沟通成本，还可以帮助一位新人快速上手业务。传统的做法是由开发人员创建一份 RESTful API 文档来记录所有的接口细节，并在程序员之间代代相传。这种做法存在以下几个问题：

1）API 接口众多，细节复杂，需要考虑不同的Http请求类型、HTTP头部信息、HTTP请求内容等，想要高质量的完成这份文档需要耗费大量的精力；

2）难以维护。随着需求的变更和项目的优化、推进，接口的细节在不断地演变，接口描述文档也需要同步修订，可是文档和代码处于两个不同的媒介，除非有严格的管理机制，否则很容易出现文档、接口不一致的情况；

Swagger2 的出现就是为了从根本上解决上述问题。它作为一个规范和完整的框架，可以用于生成、描述、调用和可视化 RESTful 风格的 WEB 服务：

• 接口文档在线自动生成，文档随接口变动实时更新，节省维护成本；

• 支持在线接口测试，不依赖第三方工具；

什么是swagger2

Swagger2 是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的web服务，现在我们使用Spring Boot 整合它。作用：

• 接口的文档在线自动生成；

• 功能测试；

常用注解

SpringBoot整合Swagger2

导入依赖

    io.springfox    springfox-swagger2    2.9.2                        swagger-models            io.swagger            ​    com.GitHub.xiaoymin    swagger-bootstrap-ui    1.8.5​    io.swagger    swagger-models    1.5.22

创建Swagger配置类

@Configuration//开启Swagger2@EnableSwagger2//配置生产环境下不可用  dev(开发)、test(测试)、prod(生产)@Profile({"dev","test"})public class Swagger2Configuration extends WebmvcConfigurationSupport {    //api接口包扫描路径    public static final String            SWAGGER_SCAN_BASE_PACKAGE = "com.lky.swagger2pro.controller";    //指定当前Swagger API文档版本    public static final String VERSION = "1.0.0";​        @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                // 接口文档的基本信息                .apiInfo(apiInfo())                .select()                // 方法需要有ApiOperation注解才能生存接口文档                //.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))                // 路径使用any风格                .paths(PathSelectors.any())                .build();    }​        private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("SpringBoot中使用Swagger2构建RestFul APIs")                .description("测试系统")                //.termsOfServiceUrl("http://www.**.com")                .version(VERSION)                .build();    }​    @Override    protected void addResourceHandlers(ResourceHandlerReGIStry registry) {        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");        registry.addResourceHandler("/webjars    @ApiModelProperty(value="书本编号")    private String bookid;​        @ApiModelProperty(value="书本名称")    private String bookname;​        @ApiModelProperty(value="书本价格")    private Double price;​        @ApiModelProperty(value="书本类型")    private String booktype;​    private static final long serialVersionUID = 1L;}

@ApiParam

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

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

案例演示

@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

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

参考地址：https://www.jianshu.com/p/fa3230ffb27c

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

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

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

修改Swagger2配置类

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

@Configuration//开启Swagger2@EnableSwagger2//配置生产环境下不可用  dev(开发)、test(测试)、prod(生产)@Profile({"dev","test"})public class Swagger2Configuration extends WebMvcConfigurationSupport {        ...    @Override    protected void addResourceHandlers(ResourceHandlerRegistry registry) {        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");    }}

修改application.yml

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

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

使用Maven package打包测试

运行测试

打开CMD，跳转到target目录，输入命令：java -jar .\xxx.jar --spring.profiles.active=prod。可以直接打开jar包修改application.yml配置文件中spring.profiles.active属性切换运行环境，具体请参考以下配置：

开发环境：dev；

生产环境：prod；

测试环境：test；

 以上就是今天有关于Swagger2的介绍和使用！

来源地址：https://blog.csdn.net/m0_62246061/article/details/128530051