Swagger2学习记录

Swagger

1、Swagger简介

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

1.1、Swagger 的优势

• 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
• 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

1.2、Swagger的用途

在开发过程中可以实时观看Api文档，包含：

• model显示你使用的实体类 带注释的信息
• controller显示你使用的请求方法 路径、参数、在线测试、响应结果等

2、部署

我这里使用的swagger2.9.2的版本

2.1、依赖

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

2.2、SwaggerConfig.java

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
}

启动报错：Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException

解决方案：
在配置文件application.properties中加入以下配置

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

如果是application.yml就加入

spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher

2.3、打开swagger-ui

网址:

http://localhost:8080/swagger-ui.html

界面：

2.4、配置Swagger

代码：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
//配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    //配置swagger信息=>apiInfo
    private ApiInfo apiInfo(){
        Contact contact = new Contact("何泽", "https://blog.csdn.net/qq_51326491?type=blog", "309***97@qq.com");
        return new ApiInfo(
                "何泽的SwaggerAPI文档", 
                "世界很大，还有诗和远方", 
                "v1.0", "urn:tos", 
                contact, 
                "Apache 2.0", 
                "http://www.apache.org/licenses/LICENSE-2.0", 
                new ArrayList()
        );
    }

界面：

2.5、Swagger配置扫描接口

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

2.6、选择开发环境使用Swagger

@Bean
    public Docket docket(Environment environment){

//设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev", "test");
        //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean b = environment.acceptsProfiles(profiles);

return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .enable(b)  //监听环境

若匹配不成功

若匹配成功

2.6、配置API文档分组

return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .groupName("heze") //分组
                .enable(b)  //监听环境

界面：

2.6、实际使用例子-（接口注释）

实体类User.java

//@Api(注释)
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

配置类SwaggerConfig.java

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev", "test");
        //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean b = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .groupName("heze") //分组
                .enable(b)  //监听环境
                .select()
                //RequestHandlerSelectors,配置要扫描接口的方式
                //basePackage:指定要扫描的包
                //any():扫描全部
                //none():不扫描
                //withClassAnnotation:扫描类上的注解，参数是一个注解的反射现象
                //withMethodAnnotation:扫描方法上的注解
                // .apis(RequestHandlerSelectors.basePackage("com.heze.controller"))
                //path(),过滤路径
                // .paths(PathSelectors.ant("/heze/**"))
                .build();
    }
    //配置swagger信息=>apiInfo
    private ApiInfo apiInfo(){
        Contact contact = new Contact("何泽", "https://blog.csdn.net/qq_51326491?type=blog", "30***97@qq.com");
        return new ApiInfo(
                "何泽的SwaggerAPI文档", 
                "世界很大，还有诗和远方", 
                "v1.0", "urn:tos", 
                contact, 
                "Apache 2.0", 
                "http://www.apache.org/licenses/LICENSE-2.0", 
                new ArrayList()
        );
    }
}

控制类HelloController.java

@RestController
public class HelloController {
    @ApiOperation("Hello控制类")
    @GetMapping(value = "/hello")
    public String hello(@ApiParam("用户名") String username){
        return "hello" + username;
    }
    
    @PostMapping(value = "/user")
    public User user(){
        return new User();
    }
}

总结：

优势：

1. 我们可以对一些接口属性添加注释信息
2. 接口文档实时更新
3. 在线测试

不足之处：

• 写注释比较麻烦