Question

我在杰克逊的泽西岛2.17上有一些RESTful API。它们都是JSON风格，并且运行良好。

但我想为开发人员生成一个优秀的RESTful Docs withJSON示例。

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

首先我尝试了ServiceDocGen Maven Plugin，

它使用Json示例直接生成HTML文档。但是它不知道杰克逊的注释，如@JsonProperty，@ JsonIgnore，所以JSON样本不准确。

然后我尝试swagger-jaxrs-maven，它知道像@JsonProperty这样的杰克逊注释，但仍然无法处理@JsonIgnore。它也是数据模式的描述，而不是样本。如果API直接返回JSON字符串，它将失败。

我也尝试过jaxrs-raml-maven-plugin，它只能使用JAXB来生成不准确的样本。

基本上我的要求很简单：

从JAX-RS注释生成端点URL和参数描述，我试过的每个插件都做得很好。
在有效负载上生成示例JSON，我不关心JSON样本数据逻辑是否正确，我关心数据结构是否准确。因此，在某些类型上设置固定数据是可以的，例如ServiceDocGen总是设置＆＃34; text＆＃34;在一个字符串上。

我认为生成JSON示例并不是那么难：首先通过Java Object树，填写随机类型的安全数据。然后调用Jackson反序列化器生成json数据。

但到目前为止，我无法找到任何maven插件正在完成这项工作。

有什么建议吗？

Answer 1

你可以试试spring-restdocs：

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

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

它根据您的终端测试（通过RestAssured或MockMvc）生成文档片段。这样，您就可以在代码和文档之间建立程序化链接。

Answer 2

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

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

然后，您可以自定义/覆盖swagger-ui的索引页面并对其进行硬编码以指向swagger.json文件的localhost路径或任何您想要的位置。

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

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）可以帮助你生成静态文档，交互式样本，并使用你的Swagger规范中的任何级别的元数据/默认值来生成可用的，人类可读的例子。

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

Answer 4

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

ObjectTreeCreator

在这个项目之后，剩下的任务很简单：

通过Java反射
通过Java反射
调用ObjectTreeCreator以从类类型
调用Jackson ObjectMapper.writeValueAsString从此对象生成Json字符串

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

我也加入了我的maven构建过程。所以每次我的构建服务器自动找到所有API并为我生成RESTful文档。

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

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

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

自动生成RESTful API示例JSON

4 个答案: