JHipster一知半解- 3.3Swagger-通讯API

回目录:JHipster一知半解

Swagger简单介绍

JHipster采用的是前后端分离的松耦合架构，那么前后端通讯的Restful API接口的描述，测试就是一个相当重要的工作。而Swagger作为一个规范和完整的框架，作为一个前后端分离的契约工具，用于生成、描述、调用和可视化 RESTful风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

swagger6.png

JHipster的swagger配置

1. maven配置

<springfox.version>2.7.0</springfox.version>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${springfox.version}</version>
    <exclusions>
        <exclusion>
            <groupId>org.mapstruct</groupId>
            <artifactId>mapstruct</artifactId>
        </exclusion>
    </exclusions>
</dependency>
    <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-bean-validators</artifactId>
    <version>${springfox.version}</version>
</dependency>

可以看出，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引用进来。

2. 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<VendorExtension>()))
            .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能正确的归类,显示.

3. 插件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)