我们可以使用 Spring rest docs 记录模型/实体吗

【问题标题】：Can we Document Model/entity with using Spring rest docs我们可以使用 Spring rest docs 记录模型/实体吗
【发布时间】：2021-08-31 07:11:25
【问题描述】：

使用 sn-ps 描述写入所有字段不是可靠的解决方案有没有办法将模型/实体实现为具有字段和描述、约束、类型的表格。

fieldWithPath("id").description("Id of Student."),
               fieldWithPath("name").description("Name of the Student."),
               fieldWithPath("contact").description("Contact of the Student."),
               fieldWithPath("marks").description("Marks of the Student."));

【问题讨论】：

标签： spring spring-boot parameters mockmvc spring-restdocs

【解决方案1】：

直接记录实体正是 Spring REST Docs 旨在避免的。如果这是您想要采用的方法，那么 Spring REST Docs 不是适合该工作的工具。

Spring REST Docs 是基于这样一种信念而构建的，即在记录 REST API 时，应该使用 HTTP 请求和响应来生成该文档。这可以确保文档准确地描述了服务期望接收的请求以及它将发送的响应。

如果您尝试使用实体来记录您的 API，您将忽略在将实体序列化为 JSON 时可能应用于该实体的转换。这可能会导致文档不准确，因为序列化可能会省略一些实体的属性、更改其中一些属性的名称，甚至完全更改结构。

【讨论】：