我该如何使用自己的注释来生成Swagger文档？

Question

我该如何使用自己的注解来构建Swagger UI页面呢？例如，我定义了一个注解并使用它：

    @PUT
    @MyOwnAnnotationForAdditionalPropInSwagger(value = "Some text")
    @Path( "/{carId}" )
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    @ApiOperation(
        value = "Updates car info"
    )
    public Response patchItem(@ApiParam(value = "Fields to update") Car item) {
            /*some code*/
    }

之后，我可能需要从swagger-core中扩展一些类，并指定扫描我的注释（@MyOwnAnnotationForAdditionalPropInSwagger）。

结果，我希望在swagger ui中看到带有我的文本的附加列。

我该如何实现它？我需要扩展哪个类？

- Alexiuscrow

---

你有点偏离了主题，因为你没有理解 Swagger 的概念。它是一种规范，扩展它并不简单。我们有一种方法可以添加供应商扩展，这些扩展会在生态系统工具中得到支持，但随意扩展它并不是我们所支持的。 - Ron

Answer 1

Swagger 2.0支持自定义字段，在2013年就有了一个Pull Request（https://github.com/swagger-api/swagger-node/pull/47）。

尽管添加自定义字段似乎很容易，但由于它们不在Swagger 2.0规范中，因此Swagger-UI默认情况下不会显示它们。

为使其生效，您需要做以下几点。

1. 如果不存在所需的注释，请在解析器实现中（例如 swagger-core 或者 swagger-php）实现它。
2. 克隆并修改 swagger-ui 以按您希望的方式显示自定义字段。

请注意，这样做实际上会违反swagger json模式（https://github.com/swagger-api/swagger-spec/blob/master/schemas/v2.0/schema.json），并且您使用的任何第三方验证器都将失败。

- Mark

---

如何在 swagger-core 解析器中实现我的注释？ - Alexiuscrow

假设您正在使用 java，那么您将需要扩展 swagger-core 库，您可以在此处找到该库：https://github.com/swagger-api/swagger-core。您可以通过阅读文档来了解具体细节：https://github.com/swagger-api/swagger-core/wiki。 - Mark

我们在这里谈论的是完整的开发周期。这超出了问题的范围，因为答案将是实现本身。 - Mark

Answer 2

我相信你想要做的可以通过扩展Swagger核心阅读器来实现，就像Swagger文档中描述的那样。这是我其中一个项目的示例。

- user2179737