Swagger开发实践

随着系统越来越多，业务之间的关联越来越紧密，以及团队工作的分工越来越细。接口开发测试也变得频繁起来，Swagger也就自然的要用起来了，所有开发人员需要遵循Swagger接口开发规范来干活！

下面先介绍一下应用添加Swagger插件的方法

首先pom中引入依赖：

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

添加Swagger配置， 所有配置信息在官网中都有介绍，后续可以可根据需求去自己添加（目前配置已经够用了），官网链接：https://springfox.github.io/springfox/docs/current/#moving-from-swagger-springmvc

@Configuration
@EnableSwagger2
@Profile({"dev", "qa"})
public class WxdxSwaggerConfig {
@Bean
public Docket petApi() {
	return new Docket(DocumentationType.SWAGGER_2)
                .select()
                    .apis(RequestHandlerSelectors.any())
                    .build()
                .pathMapping("/")
                .genericModelSubstitutes(ResponseEntity.class)
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
 }

private List<ApiKey> securitySchemes() {
        List<ApiKey> list = new ArrayList<>();
        list.add(new ApiKey("Authorization", "Authorization", "header"));
 		return list;
 }
private List<SecurityContext> securityContexts() {
        List<SecurityContext> list = new ArrayList<>();
 		list.add(SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex("^(?!user).*$"))
                .build());
 return list;
 }

    List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
 AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
 authorizationScopes[0] = authorizationScope;
 List<SecurityReference> list = new ArrayList<>();
 list.add(new SecurityReference("Authorization", authorizationScopes));
 return list;
 }
}

注意，我们Swagger只在本地开发环境以及qa环境开放，生产环境千万不能开放，别犯傻！

访问Swagger页面方式：http://host:port/swagger-ui.html，swagger-ui.html这个页面Swagger已经给我们做好了。所以我们需要配置资源映射

@Configuration
public class SwaggerWebConfig implements WebMvcConfigurer {

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
       registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}

我们所有访问都是需要经过security认证的，所以http security 设置不能少，以esp-suites为例

http
.authorizeRequests()
.antMatchers("/spring/esp/suites/swagger-ui.html", "/spring/esp/suites/swagger-resources/**",
 "/spring/esp/suites/webjars/**", "/spring/esp/suites/v2/api-docs","/spring/esp/suites/configuration/ui", "/spring/esp/suites/configuration/security").permitAll()

OK，到这里Swagger就已经可以用了，看看swagger-ui.html 张什么样子

那我们在日常开发中如何使用呢？我们以http的POST和GET为例

@RestController
@Api(tags = "评论测试接口")
@RequestMapping("/test")
@Slf4j
public class CommentTestController {
    @ApiOperation("项目启动测试方法")
    @ApiImplicitParams({
            @ApiImplicitParam(name="username", value="用户名", defaultValue = "hello"),
 @ApiImplicitParam(name="address", value="地址", defaultValue = "world"),
 })
    @GetMapping
 public String testCommnet(@RequestParam(required = true)String username, @RequestParam(required = true)String address) {
        return username + address;
 }
}

重点关注@Api，@ApiOperation，@ApiImplicitParams，@ApiImplicitParam这几个注解，想要多了解的自己可以去官网看，这里不做展开。

@ApiOperation("添加评论")
@PostMapping("/")
public Long createComment(@RequestBody CommentReq commentReq) {
 return commentService.saveComment(commentReq);
}
POST比较简单，我们只需对我们body参数作出描述即可：

@Getter
@Setter
@ToString
@ApiModel("评论请求参数")
public class CommentReq {

    @ApiModelProperty("系统名称")
    @Enumerated(EnumType.STRING)
    private applicationEnum application;

 @ApiModelProperty("评论人")
    private String commentator;

 @ApiModelProperty("评论人邮箱")
    private String commentatorEmail;

 @ApiModelProperty("系统模块")
    private String module;

 @ApiModelProperty("实体ID")
    private String entityId;

 @ApiModelProperty("实体")
    private String entity;

 @ApiModelProperty("评论内容")
    private String content;

 @ApiModelProperty("评论的父级")
    private Long parent;

 @ApiModelProperty("@的通知人")
    private String notifier;

}