自動生成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

回答

相關問題