项目_一小时零基础入门Swagger2框架

零基础入门Swagger2框架

---

0、前言

这个笔记是在2021年8月份左右记录的，当时在做一个项目，起初是前后端不分离的，也就没去想学什么Swagger，写什么接口文档。但是一个人做前端和后端，压力真的很大，所以找了一个搭档专门做前端，项目也转变为前后端分离，我也就抽空去学了一下这个Swagger框架。

emmm，这个框架入门和使用还是很简单的，当时看在B站看的视频，笔记是我边看边敲的，一共花了一小时成功入门，但是毕竟不是自己原创，所以我设置成“转载”。

视频连接：API接口管理Swagger2实战教程。

---

1、Swagger 简介

1.1、背景

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

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

如果接口文档可以实时动态生成就不会出现上面问题，Swagger可以完美的解决上面的问题。

---

1.2、Open API 是什么？

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

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

1. 每个访问地址的类型。POST或GET。
2. 每个操作的参数。包括输入输出参数。
3. 认证方法。
4. 连接信息，声明，使用团队和其他信息。

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

OpenAPI规范（OAS）为REST API定义了一个与语言无关的标准接口，允许人和计算机发现和理解服务的功能，而无需访问源代码，文档或通过网络流量检查。正确定义后，消费者可以使用最少量的实现逻辑来理解远程服务并与之交互。

然后，文档生成工具可以使用OpenAPI定义来显示API，使用各种编程语言生成服务器和客户端的代码生成工具，测试工具以及许多其他用例。

源码和说明参照：https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#oasDocument

---

1.3、Swagger简介

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

Swagger工具包括的组件：

1. Swagger Editor ：基于浏览器编辑器，可以在里面编写Open API规范。类似Markdown具有实时预览描述文件的功能。
2. Swagger UI：将Open API规范呈现为交互式API文档。用可视化UI展示描述文件。
3. Swagger Codegen：将OpenAPI规范生成为服务器存根和客户端库。通过Swagger Codegen可以将描述文件生成html格式和cwiki形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。
4. Swagger Inspector：和Swagger UI有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。
5. Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

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

---

2、Springfox

使用Swagger时如果碰见版本更新或迭代时，只需要更改Swagger的描述文件即可。但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件（yml或json）也是一定的工作负担，久而久之就直接修改代码，而不去修改描述文件了，这样基于描述文件生成接口文档也失去了意义。

• Marty Pitt编写了一个基于Spring的组件swagger-springmvc。Spring-fox就是根据这个组件发展而来的全新项目。
• Spring-fox是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可，而不需要跟随修改描述文件。
• Spring-fox利用自身AOP特性，把Swagger集成进来，底层还是Swagger。但是使用起来确方便很多。

所以在实际开发中，都是直接使用spring-fox。

附：官网地址。

附：官方源码。

---

3、Swagger的用法

3.1、编写Spring Boot项目

编写SpringBoot项目，项目中controller中包含一个Handler，测试项目，保证程序可以正确运行。

@RestController
@RequestMapping("/people")
public class DemoController {

    @RequestMapping("/getPeople")
    public People getPeople(Long id, String name){
        People peo = new People();
        peo.setId(id);
        peo.setName(name);
        peo.setAddress("海淀");
        return peo;
    }
}

---

3.2、导入Spring-fox依赖

在项目的pom.xml中导入Spring-fox依赖。目前最新版本为2.9.2，所以导入的依赖也是这个版本。其中springfox-swagger2是核心内容的封装。其中，springfox-swagger-ui是对swagger-ui的封装。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

---

3.3、添加注解

在SpringBoot的启动类中添加@EnableSwagger2注解。添加此注解后表示对当前项目中全部控制器进行扫描，应用Swagger2。

@SpringBootApplication
@EnableSwagger2
public class MyApp {
    public static void main(String [] args){
        SpringApplication.run(MyApp.class,args);
    }
}

---

3.4、访问Swagger-UI

启动项目后在浏览器中输入"http://ip:port/swagger-ui.html"即可以访问到swagger-ui页面，在页面中可以可视化的进行操作项目中所有接口。

---

4、Swagger-UI使用

访问swagger-ui.html后可以在页面中看到所有需要生成接口文档的控制器名称。

每个控制器中间包含多所有控制器方法的各种访问方式。如果使用的是@RequestMapping进行映射，将显示下面的所有请求方式。如果使用@PostMapping将只有Post方式可以能访问，下面也就只显示Post的一个。

点击某个请求方式中try it out。

会出现界面要求输入的值。输入完成后点击Execute按钮。

下面会出现Request URL以及不同状态码响应回来的结果。

---

5、Swagger配置

可以在项目中创建SwaggerConfig.java，进行配置文档内容。

---

5.1、配置基本信息

Docket：摘要对象，通过对象配置描述文件的信息。

apiInfo:设置描述文件中info。参数类型ApiInfo

select():返回ApiSelectorBuilder对象，通过对象调用build()可以创建Docket对象。

ApiInfoBuilder：ApiInfo构建器。

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket getDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerDemoApiInfo())
                .select()
                .build();
    }
    
    private ApiInfo swaggerDemoApiInfo(){
        return new ApiInfoBuilder()
                .contact(new Contact("北京尚学堂", 
                                     "http://www.bjsxt.com",
                                     "xxx@163.com"))
                //文档标题
                .title("这里是Swagger的标题")
                //文档描述
                .description("这里是Swagger的描述")
                //文档版本
                .version("1.0.0")
                .build();
    }
}

显示效果如下：

---

5.2、设置扫描的包

可以通过apis()方法设置哪个包中内容被扫描。

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(getApiInfo())
            .select()
            .apis(RequestHandlerSelectors
                  .basePackage("com.bjsxt.controller"))
            .build();
}

---

5.3、自定义注解设置不需要生成接口文档的方法

5.3.1、自定义注解

注解名称随意。

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface NotIncludeSwagger {
    
}

5.3.2、添加规则

通过public ApiSelectorBuilder apis(Predicate selector)可以设置生成规则。

public static Predicate not(Predicate predicate) :表示不允许的条件。

withMethodAnnotation：表示此注解是方法级别注解。

@Bean
public Docket getDocket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(swaggerDemoApiInfo())
            .select()
            .apis(not(withMethodAnnotation(NotIncludeSwagger.class)))
            .build();
}

5.3.3、添加@NotIncludeSwagger注解

在不需要生成接口文档的方法上面添加@NotIncludeSwagger注解后，该方法将不会被Swagger进行生成在接口文档中。

@NotIncludeSwagger
@RequestMapping("/getPeople2")
public People getPeople2(Integer id, String name, String address){
    People peo = new People();
    peo.setId(id);
    peo.setName(name);
    peo.setAddress(address);
    return peo;
}

5.3.4、设置范围

通过public ApiSelectorBuilder paths(Predicate selector)可以设置满足什么样规则的url被生成接口文档。可以使用正则表达式进行匹配。

下面例子中表示只有以/demo/开头的url才能被swagger生成接口文档。

如何希望全部扫描可以使用paths(PathSelectors.any())。

@Bean
public Docket getDocket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(swaggerDemoApiInfo())
            .select()
            .paths(allowPaths())
            .apis(not(withMethodAnnotation(NotIncludeSwagger.class)))
            .build();
}

private Predicate<String> allowPaths(){
    return or(
            regex("/demo/.*")
    );
}

---

6、Swagger2常用注解

6.1、@Api

@Api是类上注解。控制整个类生成接口信息的内容。

• tags：类的名称。可以有多个值，多个值表示多个副本。

• description:描述，已过时。

@RestController
@RequestMapping("/people")
@Api(tags = {"mydemo"},description = "描述")
public class DemoController {
	
}

在swagger-ui.html中显示效果：

---

6.2、@ApiOperation

@ApiOperation写在方法上，对方法进行总体描述

• value：接口描述
• notes：提示信息

代码示例：

@ApiOperation(value="接口描述",notes = "接口提示信息")

在swagger-ui中显示效果：

---

6.3、@ApiParam

@ApiParam写在方法参数前面。用于对参数进行描述或说明是否为必添项等说明。

• name：参数名称
• value：参数描述
• required：是否是必须

public People getPeople(Integer id, 
                        @ApiParam(value="姓名",required = true) String name, 
                        String address){
    
}

swagger-ui显示效果如下：

---

6.4、@ApiModel

@ApiModel是类上注解，主要应用Model，也就是说这个注解一般都是写在实体类上。

• value：名称
• description：描述

代码示例：

@ApiModel(value = "人类",description = "描述")
public class People {

}

swagger-ui.html效果展示：

---

6.5、@ApiModelProperty

@ApiModelProperty可以用在方法或属性上。用于当对象作为参数时定义这个字段的内容。

• value：描述
• name：重写属性名
• required：是否是必须的
• example：示例内容
• hidden：是否隐藏。

代码示例：

@ApiModelProperty(value = "姓名",
                  name = "name",
                  required = true,
                  example = "张三")
private String name;

swagger-ui.html效果展示：

---

6.6、@ApiIgnore

@ApiIgnore用于方法或类或参数上，表示这个方法或类被忽略。和之前讲解的自定义注解@NotIncludeSwagger效果类似。只是这个注解是Swagger内置的注解，而@NotIncludeSwagger是我们自定义的注解。

---

6.7、@ApiImplicitParam

@ApiImplicitParam用在方法上，表示单独的请求参数，总体功能和@ApiParam类似。

• name：属性名
• value：描述
• required：是否是必须的
• paramType：属性类型
• dataType：数据类型

代码示例：

@PostMapping("/getPeople")
@ApiImplicitParam(name = "address",
                  value = "地址",
                  required = true,
                  paramType = "query",
                  dataType = "string")
public People getPeople(Integer id, 
                        @ApiParam(value="姓名",required = true) String name, 
                        String address){
	
}

swagger-ui.html效果展示：

如果希望在方法上配置多个参数时，使用@ApiImplicitParams进行配置。示例如下：

@ApiImplicitParams(value={
	@ApiImplicitParam(name="id",value = "编号",required = true),
	@ApiImplicitParam(name="name",value = "姓名",required = true)
})

---