利用Spring Restdocs DSL进行验证 [英] Utilize Spring Restdocs DSL for validation

问题描述

我们的REST API是通过使用Spring Restdocs以标准方式(通过mockMvc.perform(...)...andDo(document().fieldWithPath(...))语句)进行的一组测试来记录的.由于字段具有类型和强制性/可选标志，因此，我也想着可以重用此信息以用于响应主体验证在生产代码中.

our REST API is documented by set of tests using Spring Restdocs in standard way (via mockMvc.perform(...)...andDo(document().fieldWithPath(...)) statement. Since fields have type and mandatory/optional flag, I play with idea to reuse this info for purpose of response body validation also in production code.

我将Spring Restdocs移到了compile Maven范围，并将代码段创建移到了生产代码中，该代码对于src/main代码中的文档测试和响应主体拦截器都是可见的(后者仅调用ResponseFieldsSnippet.createModel方法).除以下陷阱外，一切工作正常:空集合的对象看起来像是无效的，因为框架试图将对象字段的fieldWithPath规则与不存在的数据进行匹配.

I moved Spring Restdocs to compile Maven scope and moved snippet creation to production code where it is visible for both the documenting test and response body interceptor in src/main code (the latter just calls ResponseFieldsSnippet.createModel method). Everything works fine except following pitfall: empty collection of objects looks like invalid since framework tries to match fieldWithPath rule of object field against nonexistent data.

例如，假设cat的JSON被描述为fieldWithPath("kittens[]"), fieldWithPath("kittens[].name")，则由于不满足后者的描述符，实际的JSON {"kittens":[]}显得无效.对于为了最大程度地利用文档而编造数据的测试样本，这种情况不会发生，但对于实际案例而言，这是一个问题.

For example, assuming JSON of cat is described as fieldWithPath("kittens[]"), fieldWithPath("kittens[].name"), the actual JSON {"kittens":[]} appears invalid since the latter descriptor is not satisfied. This doesn't happen for test samples where data is fabricated to maximize documentation benefit but it's issue for real cases.

基于此观察，我倾向于考虑将Restdocs DSL重复用于验证是一个坏主意.在切换到JSON架构等重量级解决方案之前，我想问一下:Restdocs是否提供某种方式将字段描述符表示为树而不是规则列表?例如，例如fieldWithPath("kittens[]", subfieldWithPath("name")). (我认为，不管我的案件有多虐待，它都是有用的.)

Based on this observation, I tend to consider reusing Restdocs DSL for validation as a bad idea. Before switching to heavy-weight solution á la JSON schema, I would like to ask: does Restdocs offer some way to express field descriptors as tree rather than list of rules? For example above, something like fieldWithPath("kittens[]", subfieldWithPath("name")). (I think it could be useful regardless of how abusing is my case.)

我浏览并细化了文档中的示例，这些文档看似很有希望，但AFAIK实际上并未涵盖这种情况，即:subsectionWithPath(跳过子树)，underPath(仅专注于子树)或ResponseFieldsSnippet.andWithPrefix(仅是列表创建的快捷方式)但仍未列出树).

I browsed and elaborated examples from documentation which seemed promising but AFAIK don't actually cover this case, namely: subsectionWithPath (which skips subtree), beneathPath (which focuses only to subtree) or ResponseFieldsSnippet.andWithPrefix (only shortcut for list creation but still list not tree).

谢谢您的意见！

推荐答案

我终于发现问题在较新的库版本1.2.5和2.0.2(我有1.2.2)中得以解决.上面的示例必须表示为

I finally found the problem is solved in newer library version, namely 1.2.5 and 2.0.2 (I had 1.2.2). The example above must be expressed as

fieldWithPath("kittens"),
fieldWithPath("kittens[]").optional(),
fieldWithPath("kittens[].name").type(STRING)

此设置表示kitten字段本身是强制性的，但允许该数组为空，因此在这种情况下不应该包含任何字段name(然后必须明确声明名称的type，因为库不能从数据中获得线索).

This setup says the kitten field itself is mandatory but the array is allowed to be empty and hence no field name is expected in such case (type of name must then be explicitly stated since library can't get clue from data).

更多信息:原始问题，

More info: original issue, example above just as project test case, another examples can be found in commits linked from issue.

(注意:升级到2.0.2 对我不起作用，因为它还需要升级Spring，这是当前不可能的.)

(Note: upgrading to 2.0.2 didn't work for me since it required also to upgrade Spring, which is not currently possible.)

原始问题的答案是否，因为Spring Restdocs仍然保留字段描述符的列表格式.但是，在此修复程序之后，似乎并不太困扰我.

The answer to original question is no, since Spring Restdocs still preserves the list format of field descriptors. However, after this fix it seems it doesn't bother me very much.

这篇关于利用Spring Restdocs DSL进行验证的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！