回目录:JHipster一知半解
Swagger简单介绍
JHipster采用的是前后端分离的松耦合架构，那么前后端通讯的Restful API接口的描述，测试就是一个相当重要的工作。而Swagger作为一个规范和完整的框架，作为一个前后端分离的契约工具，用于生成、描述、调用和可视化 RESTful风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
JHipster的swagger配置
- maven配置
2.7.0
io.springfox
springfox-swagger2
${springfox.version}
org.mapstruct
mapstruct
io.springfox
springfox-bean-validators
${springfox.version}
可以看出，JHipster使用了springfox的2.7版本作为自己的API工具（官方已经升级到3.×了，但是Jhipster迟迟没有跟进）。
这里吧mapstruct排除是由于已经在上一层依赖了mapstruct-jdk8，用了“自动”生成DTOs，之前4.5版本曾经作为正式发布过，毕竟这种直接生成代码的有点怪，之后还是撤下作为beta功能了。为了避免冲突，因而就不需要在swagger里面再声明依赖mapstruct了。
另外JHipster对swagger-ui也有一点小定制（详见webapp/swagger-ui/index.html），重写了addApiKeyAuthorization()方法，因而没有使用官方swagger-ui依赖，而是把它们放到了webapp\swagger-ui里面。\webapp\app\admin\docs\docs.component.html里面，直接作为一个iframe引用进来。
- io.github.jhipster.config.apidoc包
JHipster把swagger功能作为基础功能提供（本身可以可配置的），因而swagger是在lib包里面配置的。
- PageableParameterBuilderPlugin
这是一个分页器插件，其核心方法是apply(),通过源码可以看出，就是把前端restful接口使用Pageable参数，这个由Spring提供的分页接口，并非标准类型，那么Swagger在生成接口文档时候就无法自动识别，又这个插件在发现接口类型是Pageable.class时，把它分解为
分解成“page”，“size”，”sort“参数增加对应的API描述，供生成API界面使用。
具体可见web.rest.UserResource，其中getAllUsers()有一个@ApiParam Pageable 参数。
- SwaggerConfiguration
1)类注解
@Configuration
@ConditionalOnClass({ ApiInfo.class, BeanValidatorPluginsConfiguration.class })
@EnableSwagger2
@Import(BeanValidatorPluginsConfiguration.class)
@Profile(JHipsterConstants.SPRING_PROFILE_SWAGGER)
首先，这个是一个配置类，且仅当包含swagger的profile（默认dev是包含swagger的），和存在ApiInfo.class（位于springfox-swagger2.jar),存在BeanValidatorPluginsConfiguration.class(位于springfox-bean-validators)，我也就是上面两个maven正常依赖。
@Import(BeanValidatorPluginsConfiguration.class)是允许swagger识别javax.validation中请求参数做了一些基本的校验，如@Min，@Max，@DecimalMin，@DecimalMax，@Size，@NotNull等。
@EnableSwagger2是最关键的一个注解了（spring和swagger结合点），通过Swagger2DocumentationConfiguration启用swagger的controller，处理http请求。
swaggerSpringfoxApiDocket和swaggerSpringfoxManagementDocket
@Bean
public Docket swaggerSpringfoxManagementDocket(@Value("${spring.application.name}") String appName,
@Value("${management.context-path}") String managementContextPath,
@Value("${info.project.version}") String appVersion) {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfo(appName + " management API", "Management endpoints documentation",
appVersion, "", ApiInfo.DEFAULT_CONTACT, "", "", new ArrayList()))
.groupName("management")
.forCodeGeneration(true)
.directModelSubstitute(java.nio.ByteBuffer.class, String.class)
.genericModelSubstitutes(ResponseEntity.class)
.select()
.paths(regex(managementContextPath + ".*"))
.build();
}
根据配置，生成两个不同的Docket对外服务，这里简直是通用的代码了，完全可以套用的其他地方。值得注意的是forCodeGeneration(true)，这句声明运行swagger通过代码扫描生成API接口，因而我们的rest服务里面，基本看不到需要配置swagger的地方。（当然也失去了，生成更标准的文档的能力）
TODO 增加http://localhost:8086/#/docs中swagger切换api的下拉框
- io.github.jhipster.config.JHipsterProperties.Swagger
可配置的swagger属性.
两个Docket配置的地方不一样,这里是配置API的,application.yml中可通过jhipster.swagger修改默认的配置
default-include-pattern: /api/.*
title: jhipster API
description: jhipster API documentation
version: 0.0.1
terms-of-service-url:
contact-name:
contact-url:
contact-email:
license:
license-url:
而managerment是通过读取Spring Boot的management.context-path属性变化的,这样就能使得自定义的restful端点和原生的spring-boot控制端点在同一个url path中,例如AuditResource,LogsResource
换句话说,如果application.yml中management.context-path做了修改,AuditResource,LogsResource中的@RequestMapping也需要做对应的修改,才能使得swagger能正确的归类,显示.
- 插件module （TODO）
资源和书籍推荐
- Writing OpenAPI (fka Swagger) Specification tutorial
https://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-1-introduction/ - Spring Boot构建RESTful API与单元测试(http://blog.didispace.com/springbootrestfulapi/)
- Spring Boot中使用Swagger2构建强大的RESTful API文档(http://www.jianshu.com/p/8033ef83a8ed)
- Swagger使用指南(https://my.oschina.net/dlam/blog/808315)