Swagger在Springboot项目中的使用-技术轨迹

Swagger简介

前后端分离后，前后端之间依靠API交互，各自开发各自的。

好处：

前后端相对独立，松耦合；
前后端可以部署在不同的服务器上；
可以有一套后端，多套前端。

前后端分离产生问题：

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

解决方案：

首先制定schema[计划的大纲]，实时更新最新API，降低集成的风险；
早些年：制定word计划文档
前后端分离：
前端测试后端接口：postman
后端提供接口，需要实时更新最新的消息及改动

Swagger

号称世界上最流行的API框架
RestFul API文档在线自动生成工具=>API文档与API定义同步更新
直接运行，可以在线测试API接口
支持多种语言：（Java， PHP）

官网：https://swagger.io/

在项目中使用Swagger需要springfox jar包；

swagger2
ui

SpringBoot集成Swagger

1.新建一个SpringBoot项目，web项目

2.导入相关依赖

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

<!-- 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>

3.编写测试代码hello工程

@RestController
@RequestMapping("/hello")
public class HelloController {

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

4.配置Swagger => Config

@Configuration
@EnableSwagger2 // 开启Swagger2，可以使用了
public class SwaggerConfig {
}

5.测试运行

在这里插入图片描述

配置Swagger

@Configuration
@EnableSwagger2 // 开启Swagger2，可以使用了
public class SwaggerConfig {

    // 配置了Swagger的Docket（摘要）的bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("XXX", "https://www.baidu.com", "sqzr316@163.com");
        return new ApiInfo( "XXX",
                "XXX的SwaggerAPI文档",
                "1.0",
                "https://www.baidu.com",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());

    }
}

配置Swagger扫描接口

@Configuration
@EnableSwagger2 // 开启Swagger2，可以使用了
public class SwaggerConfig {

    // 配置了Swagger的Docket（摘要）的bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // enable表示是否启动swagger true启用，false关闭
                .enable(false)
                // 通过.select()方法得到ApiSelectorBuilder对象 来进一步选择过滤要扫描的接口
                .select()
                // .apis() 自定义要扫描的接口 传入一个请求处理的选择器
                .apis(RequestHandlerSelectors.basePackage("com.song.swagger.controller"))
                // .paths(PathSelectors.*()) 来自定义要显示的请求路径
                .paths(PathSelectors.ant("/hello/**"))
                .build();
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("XXX", "https://www.baidu.com", "sqzr316@163.com");
        return new ApiInfo("XXX",
                "XXX的SwaggerAPI文档",
                "1.0",
                "https://www.baidu.com",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
}

题目：实现swagger在生产环境不可用，开发环境可用。

思路：

通过不同开发环境下的值，来传入swagger的enable()，确定是true还是false。

通过注释获取配置文件中的属性值：@Value(“${配置文件中属性名}”)

可以实现自动转格式，前提是不出现转格式异常，例如：类型不匹配TypeMisMatch，或者FormatException

其他思路：

获取当前配置环境
判断是否是需要开启swagger的环境

@Configuration
@EnableSwagger2 // 开启Swagger2，可以使用了
public class SwaggerConfig {

//    @Value("${swaggerenable}")
//    private boolean applicationEnableSwagger; // 可以通过配置文件的值来确定是否开启swagger

    // 配置了Swagger的Docket（摘要）的bean实例
    @Bean
    public Docket docket(Environment environment) { // Environment是spring的core包中的,注意不要导错包
        // 设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev", "test");
        // 通过环境类 监控是否是 指定的profiles
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // enable表示是否启动swagger true启用，false关闭
                .enable(flag)
                // 通过.select()方法得到ApiSelectorBuilder对象 来进一步选择过滤要扫描的接口
                .select()
                // .apis() 自定义要扫描的接口 传入一个请求处理的选择器
                .apis(RequestHandlerSelectors.basePackage("com.song.swagger.controller"))
                // .paths(PathSelectors.*()) 来自定义要显示的请求路径
                .paths(PathSelectors.ant("/hello/**"))
                .build();
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("XXX", "https://www.baidu.com", "sqzr316@163.com");
        return new ApiInfo("XXX",
                "XXX的SwaggerAPI文档",
                "1.0",
                "https://www.baidu.com",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
}

配置swagger中API文档的分组

配置多个Docket的Bean即可，不同的模块中的接口，放在不同的分组中，方便管理查看。

@Configuration
@EnableSwagger2 // 开启Swagger2，可以使用了
public class SwaggerConfig {


    @Bean
    public Docket docket1() {
        // new Docket(指定swagger的版本)
        return new Docket(DocumentationType.SWAGGER_2).groupName("永旗-登录模块");
    }

//    @Value("${swaggerenable}")
//    private boolean applicationEnableSwagger; // 可以通过配置文件的值来确定是否开启swagger

    // 配置了Swagger的Docket（摘要）的bean实例
    @Bean
    public Docket docket(Environment environment) { // Environment是spring的core包中的,注意不要导错包
        // 设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev", "test");
        // 通过环境类 监控是否是 指定的profiles
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("永旗-搜索模块")
                // enable表示是否启动swagger true启用，false关闭
                .enable(flag)
                // 通过.select()方法得到ApiSelectorBuilder对象 来进一步选择过滤要扫描的接口
                .select()
                // .apis() 自定义要扫描的接口 传入一个请求处理的选择器
                .apis(RequestHandlerSelectors.basePackage("com.song.swagger.controller"))
                // .paths(PathSelectors.*()) 来自定义要显示的请求路径
                .paths(PathSelectors.ant("/hello/**"))
                .build();
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("XXX", "https://www.baidu.com", "sqzr316@163.com");
        return new ApiInfo("XXX",
                "XXX的SwaggerAPI文档",
                "1.0",
                "https://www.baidu.com",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
}

Swagger常用注释注解：

只要swaggerAPI文档的接口中存在返回实体类，就会把返回的实体类显示在swagger页面中的Model中。

实体类相关注释：

@Data
@Component
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    private String name;
    @ApiModelProperty("年龄")
    private int age;
}

接口的各种注释注解：

@RestController
@RequestMapping("/hello")
public class HelloController {

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

    @GetMapping("/user/{id}")
    @ApiOperation("获取用户实体类")
    public User getUser(@ApiParam("参数id") @PathVariable Integer id) {
        return new User();
    }

    @ApiOperation("添加User用户")
    @PostMapping("/user")
    public User updateUser(@ApiParam("填写用户信息") User user) {
        return user;
    }
}

总结

我们可以通过Swagger给一些比较难理解的属性或者接口增加注释信息
接口文档实时更新
可以在线测试

Swagger是一个优秀的工具，几乎所有的大公司都有使用它

【注意】:在正式发布的时候，关闭Swagger。这是为了安全考虑，也是为了节约运行时内存。

本文是转载文章，点击查看原文
如有侵权，请联系 lx@jishuguiji.net 删除。

相关文章