生成静态 api-doc

Question

我需要将 swagger 静态生成的 api json 文件存储在我们的 git 存储库中，以便轻松跟踪 API 更改。 与此类似 http://petstore.swagger.wordnik.com/api/api-docs/user

我已经附加了 maven 插件 https://github.com/kongchen/swagger-maven-plugin

到项目，它会为 API 生成 *.json 文件。 但是，api 和属性的顺序有时会有所不同。所以 *.json 文件在没有任何 api 更改的情况下被修改（只是顺序不同）。

然后我为每个指定了“位置”参数

@Api,
@ApiOperation
@ApiModelProperty

注解，

这主要是帮助。但是有一些服务，返回 org.jboss.resteasy.plugins.providers.multipart.MultipartFormDataInput 和 javax.ws.rs.core.Response 类，并且这些类的属性仍然是随机顺序的。 那么我用这些类的 json 表示覆盖了 /swagger-overriding-models.json

现在它工作正常。 我只是在徘徊，可能这不是最好的方法，还有其他一些可能性可以按可预测的顺序生成 api json 文件，而不会混淆“位置”和模型覆盖？

Answer 1

保证订购并不是那么简单。 Java 的反射在使用反射时不保证排序 - http://docs.oracle.com/javase/8/docs/api/java/lang/Class.html#getDeclaredFields--:

The elements in the returned array are not sorted and are not in any particular order.

当然，它通常会按申报顺序退回它们，但这没有记录，也不是 JLS 的正式组成部分。

理论上 swagger-core/swagger-maven-plugin 可以强制执行字母顺序，但它可能更不可取，因为在文档的某些方面，顺序很重要（因此"position" 属性）。

您确实提出了一个关于需求的有趣观点 - 跟踪 API 更改。我敦促您在https://github.com/swagger-api/swagger-spec 上打开一个问题，以便我们可以看看我们是否可以为它生成解决方案，或者作为规范的一种形式，或者作为一个支持工具来区分规范的版本。