自动生成RESTful API示例JSON

我在Jackson 2.17上使用了一些RESTful API。他们都是JSON风格，工作得很好。自动生成RESTful API示例JSON

但我想为开发人员生成一个好的RESTful Docs with JSON样本。

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

首先我想ServiceDocGen Maven Plugin，

它直接产生使用JSON样本HTML文档。但它不知道杰克逊注释像@JsonProperty，@JsonIgnore，因此，JSON示例是不准确的。

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

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

基本上我的要求很简单：

生成JAX-RS注释端点URL和参数说明，每次我试图插件做的非常好。
在有效负载上生成示例JSON，我不关心JSON示例数据逻辑是否正确，我关心数据结构是否准确。因此，在特定类型上设置固定数据是可以的，就像ServiceDocGen总是在字符串上设置“text”一样。

我相信生成JSON样本并不那么难：首先要通过Java对象树，填入随机类型的安全数据。然后调用Jackson解串器来生成json数据。

但直到现在我找不到任何maven插件正在做好这项工作。

有什么建议吗？

来源

2016-12-06 Justin

我终于完成了我的任务，创建了自己的Java对象创建器。帮助其他人谁具有同样的问题，我加入这个项目到GitHub上：

ObjectTreeCreator

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

找到Java反射所有API方法
通过Java反射找到每种API方法的返回类类型
调用ObjectTreeCreator从类类型生成对象
呼叫杰克逊ObjectMapper.writeValueAsString从这个对象

现在我的REST风格的文档生成器工作得非常好产生JSON字符串。生成大约300个RESTful API的html文档只需要大约10秒。

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

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

顺便说一句，我还用集成测试结果，如果它存在。

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

来源

2017-12-28 22:14:14 Justin

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

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

然后，您可以自定义/覆盖招摇的用户界面和硬编码的索引页指向本地主机路径的swagger.json文件或任何你想要的。

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

来源

2016-12-14 12:04:14 cosbor11

感谢您的回答。但是大多数基于Java的RESTful API都是从Java对象生成JSON。所以我将在将来将swagger.json与Java对象对齐时遇到很大的麻烦。 – Justin

@Justin当你说大多数Java API从Java对象生成他们的json文档而不是其他方式时，我不确定是否同意。你指的是哪些API或用例研究？ – cosbor11

我使用杰克逊，它将Java对象反序列化为Json对象 – Justin

你可以试试弹簧restdocs：

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

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

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

来源

2016-12-14 12:13:08

看起来它很有前途。但是如果测试用例仅覆盖一些jsonPath而不是所有节点，它如何从测试用例生成样本？你有样品吗？ – Justin

例如，您可以通过调用断言主体（“json字段的名称”，expectedValue）来记录响应字段。你在测试用例中检查的内容反映了生成的内容。 –

我会回应cosbor11的方向，如果您想让代码和可读文档保持同步，Swagger就是您的选择。检查出支持服务优先方法的Swagger Inflector，如Phil Hauer所述：https://blog.philipphauer.de/enriching-restful-services-swagger/

使用Inflector，您可以从API规范开始生成存根和代理，也可以在代码注释（见下文），为您生成扬鞭规格：

@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; 
    } 
}

一旦你住在扬鞭/ OpenAPISpec土地，有一吨的工具（超出招摇-UI），帮助您生成静态文件，互动的样本，并使用Swagger规范中的任何级别的元数据/默认值都可以生成可用的，可读的示例。

如果你有实现偏转板的问题，绝对伸手@olensmar在Twitter上谁直接与招摇规范和工具@fehguy工作。

来源

2016-12-16 20:53:14

自动生成RESTful API示例JSON

回答

相关问题