我第一次尝试使用 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 创建的模型?
预先感谢您的帮助和指导。
最佳答案
我目前正在开发一个非常相似的项目! 首先,如果可以的话,我建议使用 spring-hateoas 的 1.0.0.RC1 版本,因为它比 0.25.x 发行版分支有一些相当重大的生活质量改进。最重要的是,现在推荐使用 EntityModel 包装类,这意味着您可以将关系排除在基本实体规范之外。 (缺点是这降低了 OpenAPI 规范的直接效用;我还没有完全弄清楚如何协调这一点。)
其次,恐怕 swagger-codegen 方面在支持 Spring HATEOAS 方面似乎没有太多现有的工作;事实上,我一直在使用普通的 Spring“语言”生成器时遇到烦人的错误。
因此,我们要么可以为 spring-hateoas 编写自己的 swagger-codegen 生成器,要么只是大量自定义一些模板以使其“足够接近”(使用 EntityModel 包装器而不是扩展 ResourceSupport 时需要的东西较少)。到目前为止,我已经采用了后一种方法,因为它是值得的。
关于java - Swagger Codegen 3 和 Spring HATEOAS,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/56245639/