自动生成RESTfulAPI样本JSON

Question

我有一些关于 Jersey 2.17 的 RESTful API 和杰克逊。它们都是 JSON 风格，而且效果很好。

但我想为开发人员生成一个很好的 RESTful 文档 JSON 示例。

所以我尝试了一些maven插件，

首先我尝试了ServiceDocGen Maven Plugin,

它直接生成 HTML 文档和 Json 样本。但是它不知道@Json属性这样的Jackson注解，@Json忽略，所以 JSON 样本不准确。

然后我尝试了 swagger-jaxrs-maven，它知道一些像 @Json属性这样的 Jackson 注释，但仍然无法处理 @JsonIgnore。它也是数据模式的描述，而不是示例。如果API直接return一个JSON字符串会失败。

我也试过jaxrs-raml-maven-plugin，只能用JAXB生成sample，不准确

基本上我的要求很简单：

从 JAX-RS 注释生成端点 URL 和参数描述，我尝试的每个插件都做得很好。
在payload上生成样本JSON，我不关心JSON样本数据逻辑正确与否，我关心数据结构是否正确。所以在某种类型上设置固定数据是可以的，比如 ServiceDocGen 总是在字符串上设置 "text"。

我相信生成JSON样本并不难：首先遍历Java对象树，填入随机类型的安全数据。然后调用Jackson反序列化器生成json数据。

但直到现在我还找不到任何 maven 插件可以很好地完成这项工作。

有什么建议吗？

Answer 1

我认为您找不到完全可以做到这一点的工具。最好的办法是编写一个 swagger.json 文件并导入 swagger-ui webjar 依赖项。

<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>swagger-ui</artifactId>
    <version>${swagger-ui.version}</version>
</dependency>

然后您可以 customize/override swagger-ui 的索引页并将其硬编码为指向您的 swagger.json 文件或任何您想要的本地主机路径。

如果时间不是限制，您可以编写一个 Maven 插件来使用反射扫描和反向工程您的 JAX-RS 注释以生成 swagger json 文件。就个人而言，我更喜欢只维护一个 json 文件并从该文件生成我的 API 和模型。

Answer 2

你可以尝试 spring-restdocs:

https://github.com/spring-projects/spring-restdocs

http://docs.spring.io/spring-restdocs/docs/current/reference/html5/

它会根据端点测试（通过 RestAssured 或 MockMvc）生成文档片段。这样，您的代码和文档之间就有了程序化的 link。

Answer 3

我赞同 cosbor11 的方向，如果您想使代码和可读文档保持同步，Swagger 是必经之路。查看 Swagger Inflector，它支持 Phil Hauer 描述的服务优先方法：https://blog.philipphauer.de/enriching-restful-services-swagger/

使用 Inflector，您可以从 API 规范开始生成存根和代理，或者您可以先启动服务，您的代码注释（见下文）为您生成 Swagger 规范：

@Api(value = "customers", description = "RESTful API to interact with customer resources.")
@Path("customers")
public class CustomerResource {

    @ApiOperation(value = "Get all customers", notes = "Get all customers matching the given search string.", responseContainer = "List", response = Customer.class)
    @GET
    @Path("/")
    @Produces(MediaType.APPLICATION_JSON)
    public List<Customer> getCustomers(
            @ApiParam(value = "The search string is used to find customer by their name. Not case sensetive.", required = false, defaultValue = "") @QueryParam("search") String searchString,
            @ApiParam(value = "Limits the size of the result set", required = false, defaultValue = "50") @QueryParam("limit") int limit) {
        List<Customer> customers = dao.getCustomers(searchString, limit);
        return customers;
    }
}

一旦您居住在 Swagger/OpenAPISpec 土地上，就会有大量工具（超越 swagger-ui）帮助您生成静态文档、交互式示例，并使用任何级别的 metadata/defaults 在您的 Swagger 规范中生成可用的、人类可读的示例。

如果您在实施 Inflector 时遇到问题，请务必联系 Twitter 上的@olensmar，他直接与 @fehguy 一起处理 Swagger 规范和工具。

Answer 4

我终于通过创建自己的 Java 对象创建器完成了我的任务。为了帮助有同样问题的其他人，我将这个项目添加到 GitHub:

ObjectTreeCreator

完成这个项目，剩下的任务很简单：

通过Java反射找到所有API方法
通过Java反射
调用 ObjectTreeCreator 从 class 类型生成一个对象
调用 Jackson ObjectMapper.writeValueAsString 以从该对象生成 Json 字符串

现在我的 RESTful 文档生成器运行良好。它只需要大约 10 秒就可以生成大约 300 RESTful API 秒的 html 文档。

我还添加到我的 maven 构建过程中。所以每次我的构建服务器都会自动找到所有 API 并为我生成 RESTful 文档。

生成的 JSON 结构与真实 API 响应完全相同。

顺便说一下，我也使用了集成测试结果（如果存在的话）。

ObjectTreeCreator 仅在不存在集成测试时使用。

自动生成RESTfulAPI样本JSON

automatically generate RESTful API sample JSON

documentation

rest

json

dynamically-generated