Swagger笔记

Swagger

  • 了解Swagger的概念及作用
  • 了解前后端分离
  • 在springboot中集成swagger

Swagger简介

  • 前言：

　　接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要，但是由于项 目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接 口文档和实际情况不一致。

　　很多人员会抱怨别人写的接口文档不规范，不及时更新。当时当 自己写的时候确实最烦去写接口文档。这种痛苦只有亲身经历才会牢 记于心。

　　如果接口文档可以实时动态生成就不会出现上面问题。

　　Swagger 可以完美的解决上面的问题。

  • Open API：

　　Open API 规范(OpenAPI Specification)以前叫做 Swagger 规范，是REST API 的 API 描述格式。

　　Open API 文件允许描述整个 API，包括：

　　　　· 每个访问地址的类型。POST 或 GET。

　　　　·每个操作的参数。包括输入输出参数。

　　　　·认证方法。

　　　　·连接信息，声明，使用团队和其他信息。

　　Open API 规范可以使用 YAML 或 JSON 格式进行编写。这样更利于我们和机器进行阅读。

　　OpenAPI 规范（OAS）为 RESTful API 定义了一个与语言无关的标 准接口，允许人和计算机发现和理解服务的功能，而无需访问源代码， 文档或通过网络流量检查。正确定义后，消费者可以使用最少量的实 现逻辑来理解远程服务并与之交互。然后，文档生成工具可以使用 OpenAPI 定义来显示 API，使用各 种编程语言生成服务器和客户端的代码生成工具，测试工具以及许多 其他用例。

  • Swagger 简介：

　　Swagger 是一套围绕 Open API 规范构建的开源工具，可以帮助设 计，构建，记录和使用 REST API。

　　Swagger 工具包括的组件：

　　　　Swagger Editor ：基于浏览器编辑器，可以在里面编写 Open API规范。类似 Markdown 具有实时预览描述文件的功能。

　　　　Swagger UI：将 Open API 规范呈现为交互式 API 文档。用可视化UI 展示描述文件。

　　　　Swagger Codegen：将 OpenAPI 规范生成为服务器存根和客户端 库。通过 Swagger Codegen 可以将描述文件生成 html 格式和 cwiki 形 式的接口文档，同时也可以生成多种言语的客户端和服务端代码。

　　　　Swagger Inspector：和 Swagger UI 有点类似，但是可以返回更多 信息，也会保存请求的实际参数数据。

　　　　Swagger Hub：集成了上面所有项目的各个功能，你可以以项目 和版本为单位，将你的描述文件上传到 Swagger Hub 中。在 Swagger Hub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

　　　　使用 Swagger，就是把相关的信息存储在它定义的描述文件里面（yml 或 json 格式），再通过维护这个描述文件可以去更新接口文档， 以及生成各端代码。

SpringBoot集成Swagger

SpringBoot集成Swagger => springfox，两个jar包

使用Swagger

要求：jdk 1.8 + 否则swagger2无法运行

步骤：

  1. 新建一个SpringBoot-web项目

  2. 添加Maven依赖（注意：2.9.2版本之前，之后的不行）

    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

  3. 编写HelloController，测试Swagger

    @RestController
public class HelloController {

    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }

  4. 在配置类编写SwaggerConfig，并配置注解

    @Configuration
@EnableSwagger2         //开启Swagger2
public class SwaggerConfig {
}

  5. 访问http://localhost:8080/swagger-ui.html#，可以看到Swagger-ui界面

    image-20201119192400412

配置Swagger

  1. Swagger通过Docekt的bean实例实现
// 配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
        }

  1. 配置Swagger信息可以通过——>apiInfo 

    //配置Swagger信息->apiInfo
    private ApiInfo apiInfo(){

        Contact contact = new Contact("PlutoWu", "https://www.plutowu.top/", "p1utowu@qq.com");

        return new ApiInfo(
                "Pluto的SwaggerAPI文档",
                "PlutoWu Swagger",
                "v1.0",
                "https://www.plutowu.top/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

  2. Docekt关联apiInfo以实现Swagger-UI页面的自主化

@Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
                }

  1. 重新访问http://localhost:8080/swagger-ui.html#，如下图所示

    image-20201119185622792

配置Swagger扫描接口

  1. 通过设置Docket下的select()实现对扫描接口的配置

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            // RequestHandlerSelectors，配置要扫描接口的方式
            // basePackage指定要扫描的包
            // any()：扫描全部
            // none()：不扫描
            // withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
            // withMethodAnnotation：扫描方法上的注解
            .apis(RequestHandlerSelectors.basePackage("com.pluto.swagger.controller"))
            // path()：过滤什么路径
            // .paths(PathSelectors.ant("/pluto/**"))
            .build();
 }

  2. 现在只能扫描到controller包下的接口

    image-20201119193024261

  3. 以下为可选的方式包括指定接口、包以及路径

// RequestHandlerSelectors，配置要扫描接口的方式
// basePackage指定要扫描的包
// any()：扫描全部
// none()：不扫描
// regex(final String pathRegex)：通过正则表达式控制
// ant(final String antPattern)：通过ant()控制
// withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
// withMethodAnnotation：扫描方法上的注解
// path()：过滤什么路径
.paths(PathSelectors.ant("/pluto/**"))

配置Swagger开关

  1. 在Docket下添加如下配置即可实现开关Swagger

    @Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(false) // 开关Swagger
            .build();
     }

    置于false即可看到以下页面

    image-20201119193738092

  2. 如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？

    • 判断是否为生产环境 flag = false
    • 注入enable (flag)
# 应用名称
spring.application.name=swagger-demo
# 应用服务 WEB 访问端口
server.port=8080
spring.profiles.active=dev
@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(true)
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.pluto.swagger.controller"))
               .paths(PathSelectors.ant("/pluto/**"))
               .build();
    }

image-20201119195647700

同理，配置文件更改环境为prod即可切换为发布版本，端口也要相应更改为8082。

配置API分组

  1. 默认分组为default，可以通过groupName()方法进行配置分组
return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("Pluto") // 配置分组
                .enable(true)
                .select()
                ......
  1. 重启服务页面显示分组

image-20201119200703587

  1. 配置多个分组——配置多个Docket（别忘了@Bean注解，否则无法注册为实例）
@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("YaYa");
}

@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("XiaoGuo");
}

@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("Lily");
}
  1. 重启服务，页面可见多个分组

image-20201119201309428

实体配置

  1. 新建实体类
@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    public String username;

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

    ......
  1. 配置Controller类，添加请求接口
// 只要我们的接口中，返回值存在实体类，它就会被扫描到Swagger中
    @PostMapping(value = "/user")
    public User user(){
        return new User();
    }
  1. 重启服务，查看实体类被扫描

image-20201119202436940

注意：并非@ApiModel让实体类被扫描，而是只要出现在接口方法的返回值上的实体类都会被扫描到，@ApiModelProperty和@ApiModel只是为实体类添加注释所用。

  • @ApiModel为类添加注释
  • @ApiModelProperty为类具体属性添加注释

常用Swagger注解

Swagger的所有注解定义在io.swagger.annotations包下

下面列一些经常用到的，未列举出来的可以另行查阅说明：

Swagger注解 简单说明
@Api(tags = “xxx模块说明”) 作用在模块类上
@ApiOperation(“xxx接口说明”) 作用在接口方法上
@ApiModel(“xxxPOJO说明”) 作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true) 作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”) 作用在参数、方法和字段上，类似@ApiModelProperty

Swagger(GET/POST)测试功能

  1. Controller方法前添加==@ApiOeration==注释
@ApiOperation("Post测试类")
    @PostMapping(value = "/post")
    public User post(@ApiParam("用户名") User user){
        return user;
    }
  1. 重启服务进入Swagger-ui界面进行测试

image-20201119205520715

image-20201119205838266

image-20201119205659138

总结：

  • 添加注释到一些较难理解的接口或属性，以便增加可读性
  • 可在线测试
  • API实时更新

==注意：在正式版本发布时，需关闭Swagger！！！==

  • 处于安全考虑
  • 节省内存

拓展（Swagger皮肤切换）

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

image-20201119210101794

image-20201119210351394

笔记
Swagger

本博客所有文章除特别声明外，均采用 CC BY-SA 4.0 协议 ，转载请注明出处！