swagger

Swagger

接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要，但是由于项 目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接 口文档和实际情况不一致。 很多人员会抱怨别人写的接口文档不规范，不及时更新。当时当 自己写的时候确实最烦去写接口文档。这种痛苦只有亲身经历才会牢 记于心。

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

Swagger简介

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

• 号称世界上最流行的API框架；
• RestFul Api文档在线生成工具=》Api文档与API定义同步更新
• 直接运行，可以在线测试API接口；
• 支持多种语言：（java、php）。

Swagger集成

在项目中使用Swagger需要springbox；

• swagger2；
• swagger-ui

导入maven依赖：

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

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

配置Swagger

/**
 * @EnableSwagger2:开启swagger2
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

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

    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("徐甲一", "urn:tos", "xujaiyi111@qq.com");
        return new ApiInfo("xjy的API文档",
                "即使在小的帆也能远航",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "https://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

Swagger配置扫描接口

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

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        //是否启用swagger，如果为false，则swagger不能在浏览器中访问
        .enable(false)
        .select()
        /**
                 *RequestHandlerSelectors：配置要扫描接口的方式;
                 * basePackage：指定要扫描的包;
                 * any()：扫描全部；
                 * none（）：不扫描；
                 * withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                 * withMethodAnnotation：扫描方法上的注解
                 */
        .apis(RequestHandlerSelectors.basePackage("com.xjy.controller"))
        //paths()：过滤什么路径
        .paths(PathSelectors.ant("/hello/**"))
        .build();
}

select后面是select一套，要加其他的配置只能是之前加。

面试题：我只希望在生产环境中使用swagger，在发布的时候不使用，应该怎么做？

• 判断是不是生产环境，flag=false
• 注入enable（lage）

//设置要显示的swagger环境
Profiles profiles = Profiles.of("dev", "test");

//获取项目的环境,通过environment.acceptsProfiles来判断是否处在自己设定的环境当中.
boolean flag = environment.acceptsProfiles(profiles);

配置API文档的分组

通过groupName("")配置多个Docket，(在多人开发中，每个开发者配置一个自己的Swagger，方便管理)

@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");
}

实体类配置

/**
 * @ApiModel  @ApiModelProperty：给生成的文档加一个注释
 * 在swagger显示实体类信息时，如果是private修饰，需要有get、set方法。
 * @author 徐甲一
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;

}

在swagger显示实体类信息时，如果是private修饰，需要有get、set方法。

@RestController
public class HelloController {

    /**
     * 只要接口中，返回值中存在实体类，他就会被扫描到swagger中
     * @return
     */
    @ApiOperation("Hello实体类")
    @PostMapping(value = "/user")
    public User user() {
        return new User();
    }

    @GetMapping("/user/hello")
    public String Hello(@ApiParam("用户名") String username) {
        return "hello" + username;
    }


}

@ApiOperation是给方法加注释的

@ApiParam是给传递的参数加注释

总结

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

【注意】在正式发布时要关闭Swagger，可以保证安全和避免浪费性能 。