Swagger简介与使用

发表于 | 分类于
字数统计: 890 | 阅读时长 ≈ 4

背景：前后端分离时代的来临 Vue+Springboot

后端时代：前端至负责管理静态页面；html==>后端。模板引擎jsp=>后端是主力

前后端分离时代：

  • 后端：后端控制层，服务层，数据访问层
  • 前端：前端控制层，视图层
    • 伪造后端数据，json。不需要后端，前端工程依然能够跑起来
  • 前后端交互：API
  • 前后端相互独立，松耦合
  • 前后端甚至可以分布在不同的服务器上

产生的一个问题：

  • 前后端集成联调，前后端人员无法做到“及时协商，尽早解决”，最终导致问题爆发。

解决方案：

  • 首先指定schema，实时更新最新的API，降低集成的风险
  • 早些年：
    • 指定word计划文档；
    • 前端测试后端接口：postman
    • 后端提供接口，需要实时更新最新的消息及改动
  • Swagger产生 ！

Swagger简介

  • 号称世界上最流行的API框架
  • ReatFul API 文档在线自动生成工具=>API文档与API自动更新
  • 直接运行，可以在线测试API接口
  • 支持多种语言

Springboot集成Swagger

1、创建springboot项目并导入web依赖

2、导入相关依赖

1
2
3
4
5
6
7
8
9
10
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

3、编写一个hellworld

4、编写Swagger配置类

1
2
3
4
5
@Configuration
@EnableSwagger2  // 开启Swagger2
public class SwaggerConfig {

}

5、测试访问：http://localhost:8080/swagger-ui.html

配置Swagger

Swagger的bean实例 Docket

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
@Configuration
@EnableSwagger2  // 开启Swagger2
public class SwaggerConfig {

    // 配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket( new DocumentationType("swagger", "2.0"))
                .apiInfo(apiInfo());
    }

    // 配置Swagger的apiInfo
    private ApiInfo apiInfo(){
        Contact contact = new Contact("sweetboyZhang", "https://sweetboyZhang.github.io", "2824199842@qq.com");
        return new ApiInfo(
                "My Swagger API 文档",
                "这是一个Swagger测试",
                "1.0",
                "https://sweetboyZhang.github.io",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
    
}

配置Swagger扫描路径

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@Bean
public Docket docket(){
    return new Docket( new DocumentationType("swagger", "2.0"))
            .apiInfo(apiInfo())
            .select()
            // RequestHandlerSelectors配置要扫描接口的方式
            // basePackage 指定要扫描的包
            // any() 扫描全部
            // none() 不扫描
            // withClassAnnotation(xxx.class)扫描类上的注解
            // withMethodAnnotation(xxx.class)扫描方法上的注解
            .apis(RequestHandlerSelectors.basePackage("com.zyz.controller"))
            // .paths 过滤路径
            .build();
}

根据环境是否开启Swagger

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
@Bean
public Docket docket(Environment environment){
    // 设置要显示的Swagger环境
    Profiles profiles = Profiles.of("dev");
    // 获取项目环境
    boolean flag = environment.acceptsProfiles(profiles);
    return new Docket( new DocumentationType("swagger", "2.0"))
            .apiInfo(apiInfo())
            .enable(flag)// 设置是否启动Swagger
            .select()
            // RequestHandlerSelectors配置要扫描接口的方式
            // basePackage 指定要扫描的包
            // any() 扫描全部
            // none() 不扫描
            // withClassAnnotation(xxx.class)扫描类上的注解
            // withMethodAnnotation(xxx.class)扫描方法上的注解
            .apis(RequestHandlerSelectors.basePackage("com.zyz.controller"))
            // .paths 过滤路径
            .build();
}

application-dev.properties

1
2
# 生产环境
server.port=8080

application-pro.properties

1
2
# 上线环境
server.port=8081

application.properties

1
2
# 激活生产环境
spring.profiles.active=dev

配置分组

方便多人协同开发

1
.groupName("zyz")
1
2
3
4
5
6
7
8
9
10
11
12
@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}
@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}
@Bean
public Docket docket3(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}

配置实体类

1
2
3
4
5
6
// 只要接口中的返回值有实体类，Swagger就会扫描到
@ApiOperation("user控制方法")// 方法注释
@PostMapping("/user")
public User user(@ApiParam("用户名")String name,@ApiParam("密码") String password){
    return new User(name,password);
}
1
2
3
4
5
6
7
8
9
10
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("用户实体类")// 注释
public class User {
    @ApiModelProperty("用户名")
    private String name;
    @ApiModelProperty("密码")
    private String password;
}