如何使用自己的 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 中看到额外的列。

我怎么能意识到呢？ 我需要扩展什么课程？

Answer 1

swagger 2.0 支持自定义字段，早在 2013 年就有一个拉取请求（ 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 ）和任何第三方验证器你可能使用会失败。

Answer 2

我相信您尝试做的事情可以通过扩展swagger 文档中所述的 swagger 核心阅读器来实现。 这是我的一个项目中的一个例子。