【java框架】SpringBoot(3) -- SpringBoot集成Swagger2

1.SpringBoot web项目集成Swagger2

1.1.认识Swagger2

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和接口文档系统作为服务器以同样的速度来更新。文档的接口方法，参数和模型紧密集成到服务器端的代码，使用API来保持前后端接口的更新同步。解决了前后端分离开发中的痛点。

 

Swagger2官方文档：https://swagger.io

 

1.2.集成Swagger2初体验

①基于SpringBoot Initializr来创建一个web项目，并引入相关依赖：

<!--引入swagger2依赖及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>

依赖组件下载地址：https://mvnrepository.com/artifact/io.springfox

②创建Swagger2Config配置类，增加API应用配置信息：

//将此类交给Spring管理，表示一个配置类
@Configuration
//开启Swagger2
@EnableSwagger2
public class Swagger2Config {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录
     *
     * @return 返回Swagger的Docket配置Bean实例
     */
    @Bean
    public Docket createRestApi(Environment environment) {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)  //enable是否启动swagger，如果为False，则swagger不能在浏览器中访问
                .select()
                //指定API对象扫描哪个包下面的controller
                //参数any()：扫描全部； none()：都不扫描
                //withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation：扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.fengye.swagger2.controller"))
                //过滤什么路径
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return  返回API基本信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //Swagger2展示界面的标题（重要）
                .title("Spring Boot使用Swagger2构建的Restful API")
                //描述信息（主要）
                .description("Swagger2 makes develop more easily")
                .version("1.0")
                .termsOfServiceUrl("https://swagger.io/docs")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                //作者信息
                .contact(new Contact("fengye", "https://www.cnblogs.com/yif0118/",
                        "hyfmailsave@163.com")).build();
    }
}

③创建Controller接口类测试接口：

@RestController
@RequestMapping("/oss")
@Api(value = "接口演示",description = "用来演示Swagger的一些注解")
public class TestController {
    @ApiOperation(value="修改用户密码", notes="根据用户id修改密码")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="query", name = "userId", value = "用户ID", required = true, dataType = "Integer"),
            @ApiImplicitParam(paramType="query", name = "password", value = "旧密码", required = true, dataType = "String"),
            @ApiImplicitParam(paramType="query", name = "newPassword", value = "新密码", required = true, dataType = "String")
    })
    @RequestMapping("/updatePassword")
    public String updatePassword(@RequestParam(value="userId") Integer userId, @RequestParam(value="password") String password,
                                 @RequestParam(value="newPassword") String newPassword){
        if(userId <= 0 || userId > 2){
            return "未知的用户";
        }
        if(StringUtils.isEmpty(password) || StringUtils.isEmpty(newPassword)){
            return "密码不能为空";
        }
        if(password.equals(newPassword)){
            return "新旧密码不能相同";
        }
        return "密码修改成功!";
    }
}

④启动项目，访问接口url地址信息：

http://项目实际地址/swagger-ui.html

2.Swagger高级配置应用

2.1.多场景启用配置

在实际开发场景中，有时我们需要在开发时使用Swagger接口文档，但是在实际上线或生产环境中并不想使用，那么就需要读取实际环境信息进行启动Swagger。

具体配置如下：

//将此类交给Spring管理，表示一个配置类
@Configuration
//开启Swagger2
@EnableSwagger2
public class Swagger2Config {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录
     *
     * @return 返回Swagger的Docket配置Bean实例
     */
    @Bean
    public Docket createRestApi(Environment environment) {
        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev", "test");
        //获取当前项目中的环境，看是否一致
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)  //enable是否启动swagger，如果为False，则swagger不能在浏览器中访问
                .select()
                //指定API对象扫描哪个包下面的controller
                //参数any()：扫描全部； none()：都不扫描
                //withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation：扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.fengye.swagger2.controller"))
                //过滤什么路径
                .paths(PathSelectors.any())
                .build();
    }
}

同时设置相关的环境配置信息：

application.properties：

#确认启用开发环境--swagger启用
spring.profiles.active=dev

application-dev.properties与application-pro.properties：

server.port=8081  #开发环境
server.port=8082  #生产环境

2.2.接口文档分组显示

在实际项目开发过程中，一个项目开发者有成百上千个接口文档，如果不进行分组，那么集合在一个Swagger页面中的接口就会很多，不便于查询和展示，

那么对不同的开发者来进行分组显示，不同的开发者命名自己的开发接口，就非常有必要了。

而Swagger配置中提供了groupName()进行分组显示：

@Bean
    public Docket devDocket1(){
        //由开发者自己管理对应的类，编写controller对应的包
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }

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

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

分组效果：

2.3.Swagger Api接口注释

常用到的注解有：

• Api
• ApiModel
• ApiModelProperty
• ApiOperation
• ApiParam
• ApiResponse
• ApiResponses
• ResponseHeader

①Api

Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式：

@Api(value = "/user", description = "Operations about user")

②ApiOeration

ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义,使用方式：

@ApiOperation(
          value = "Find purchase order by ID",
          notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
          response = Order,
          tags = {"Pet Store"})

③ApiParam

ApiParam请求属性,使用方式：

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)

与Controller中的方法并列使用。

④ApiResponse

ApiResponse：响应配置，使用方式：

@ApiResponse(code = 400, message = "Invalid user supplied")

⑤ApiResponses

ApiResponses：响应集配置，使用方式：

 @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

⑥ResponseHeader

响应头设置，使用方法：

@ResponseHeader(name="head1",description="response head conf")

⑦其它

• @ApiImplicitParams：用在方法上包含一组参数说明；
• @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

1. paramType：参数放在哪个地方
2. name：参数代表的含义
3. value：参数名称
4. dataType： 参数类型，有String/int，无用
5. required ： 是否必要
6. defaultValue：参数的默认值

• @ApiResponses：用于表示一组响应；
• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息；

1. code： 响应码(int型)，可自定义
2. message：状态码对应的响应信息

• @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候；
• @ApiModelProperty：描述一个model的属性。

更详细Swagger接口Api注解说明请参阅简书：https://www.jianshu.com/p/12f4394462d5

 

本博客写作参考文档相关：

https://www.jianshu.com/p/66a14ea07622  《简书--Swagger使用手册》

https://www.jianshu.com/p/12f4394462d5    《简书--Swagger常用注解说明》

https://swagger.io/irc/

示例代码已上传至Github地址：

https://github.com/devyf/SpringBoot_Study/tree/master/springboot_swagger2