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;

}