java - Swagger Codegen 3 和 Spring HATEOAS

Question

我第一次尝试使用 OAS 3.0、Swagger Codegen、Spring MVC 和 Spring HATEOAS 创建 RESTful API。我想使用 OAS 定义来生成文档和服务器/客户端 stub ，并使用 HATEOAS 创建超链接相关资源。

我目前的资源已扩展 ResourceSupport并可以添加我的链接，以便回复具有 _embedded和_links我所期望的领域。我的问题是如何正确映射 HATEOAS Resource到 Swagger codegen 生成的模型。我的 OAS 定义与 hal+json 匹配响应，因此 swagger 模型和我的 HATEOAS Response 中的字段是相同的.

有没有办法轻松映射这些？我也愿意接受我对这一点的错误解释，并且这些框架并没有真正融合在一起。

美洲国家组织示例:

responses:
  200:
    description: ...
    content:
      application/hal+json:
        schema:
          $ref: '#/components/schemas/OasPersonResponse'

components:
  schemas:
    OasPersonResponse:
      type: object
          properties:
            firstName:
              type: string
            lastName:
              type: string
            _links:
              type: object
              properties:
                self:
                  type: object
                  properties:                  
                    href:
                    type: string

Resource示例:

public class PersonResource extends ResourceSupport {
  private final Person person;

  public PersonResource(Person person) {
    this.person = person;
  }

  public String getFirstName() {
    return person.getFirstName();
  }

  public String getLastName() {
    return person.getLastName();
  }
}

Controller 示例:

@Controller
public class PersonController implements PersonApi {

  @Override
  public ResponseEntity<OasPersonResponse> getPersonById(Integer personId) {
    Person person = someDb.getPerson(personId);
    PersonResource personResource = new PersonResource(person);

    personResource
      .add(linkTo(methodOn(PersonController.class)
        .getPersonById(personId))
      .withSelfRel();

    Resource<PersonResource> returnResource = 
      new Resource(personResource);

    return new ResponseEntity<>(returnResponse, HttpStatus.OK);
}

我的问题是 swagger codegen 生成的 stub 期望返回类型为 ResponseEntity<OasPersonResponse>但有一个引用Resource<PersonResource> 。两者OasPersonResponse和PersonResource表示相同的数据，但 OasPersonResponse明确定义 _links对象，而响应为 PersonResource被序列化为 _links对象。

有没有一种简单的方法可以将 HATEOAS 资源转换为 swagger codegen 创建的模型？

预先感谢您的帮助和指导。

Answer 1

我目前正在开发一个非常相似的项目!首先，如果可以的话，我建议使用 spring-hateoas 的 1.0.0.RC1 版本，因为它比 0.25.x 发行版分支有一些相当重大的生活质量改进。最重要的是，现在推荐使用 EntityModel 包装类，这意味着您可以将关系排除在基本实体规范之外。 (缺点是这降低了 OpenAPI 规范的直接效用；我还没有完全弄清楚如何协调这一点。)

其次，恐怕 swagger-codegen 方面在支持 Spring HATEOAS 方面似乎没有太多现有的工作；事实上，我一直在使用普通的 Spring“语言”生成器时遇到烦人的错误。

因此，我们要么可以为 spring-hateoas 编写自己的 swagger-codegen 生成器，要么只是大量自定义一些模板以使其“足够接近”(使用 EntityModel 包装器而不是扩展 ResourceSupport 时需要的东西较少)。到目前为止，我已经采用了后一种方法，因为它是值得的。