java - 如何为 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 中看到带有我的文本的附加列。

我怎样才能实现它？我需要扩展什么类(class)？

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 )，并且您可能使用的任何第三方 validator 都将失败。