Swagger 无法为 HTTP 的 "PATCH" 方法生成文档。

Question

我已经按照以下博客入口的步骤进行了操作: http://kingsfleet.blogspot.co.uk/2014/02/transparent-patch-support-in-jax-rs-20.html ，并参考了下面这个链接中提供的样例代码： https://github.com/jersey/jersey/tree/2.6/examples/http-patch 通过Jersey 2.6创建支持HTTP "PATCH" 方法的终端点 版本依赖关系:

-Jersey: 2.6
-swagger-jersey2-jaxrs_2.10: 1.3.12

问题？

为什么Patch端点没有列入Swagger UI文档的一部分？

分析：

如果我使用此注释进行注释，则会生成该端点的文档，但没有交互。

@com.wordnik.swagger.jaxrs.PATCH

配置

JerssyApplicationInitializer

packages(true, "com.test.account.endpoint", "com.wordnik.swagger.jaxrs.json");
        //Swagger Configuration
        register(new ApiListingResourceJSON(), 10);
        register(JerseyApiDeclarationProvider.class);
        register(JerseyResourceListingProvider.class);

        //Genson Converter
        register(GensonJsonConverter.class, 1);
        register(createMoxyJsonResolver());

我不确定是否有遗漏，任何帮助或指导都将是有益的。

补丁方法文档：

 public static final String PATCH_MEDIA_TYPE = "application/json-patch+json";
    @PATCH
        //@com.wordnik.swagger.jaxrs.PATCH
        @PreAuthorize(userAuthenticationRequire=true)
        @Consumes(PATCH_MEDIA_TYPE)
        @Path("{id: .\\d+}")
        @ApiOperation(value = "Update Client Details in UIM System."
                    , response = State.class
                    , notes="Requesting User, should be the owner of the Client."
                    , consumes = PATCH_MEDIA_TYPE)
        @ApiResponses({
            @ApiResponse(code = _401, message = "If the access token is invalid.", response = String.class),
            @ApiResponse(code = _498, message = "If the access token is expired.", response = String.class),
            @ApiResponse(code = _420, message = "If Provided Input is not valid according to requirment specification."),
            @ApiResponse(code = _404, message = "If no client/app Found."),
            @ApiResponse(code = _200, message = "If Client Account has been Updated successfully. ", response=String.class)
        })
        public State updateClientDetails(@ApiParam(value="Client Id to be Updated.", required=true) @PathParam(CLIENT_ID) String clientId
                , @ApiParam(value = "Updated field and Value.", required = true) final State newState){
            //LOG.info("[ENTRY]- Received requst for updating Client {} from System.", clientId);
            System.out.println("----->" + someBean.test());
            //LOG.info("[EXIT]- Client Id {} Updation has been completed.", clientId);
            Test t = new Test();
            t.name = "Hello Test";
            System.out.println(t.name);
            return newState;
        }

- Jayaram

---

当你说它没有生成时，你是看UI还是生成的Swagger JSON？ - Ron

你能否编辑问题并附上一个带有注释的示例方法签名？ - Ron

@Ron 嗯，已经编辑好了，请看一下...感谢你抽出时间来看 :) - Jayaram

另外还有两个问题 - 资源是否使用了@Api进行注释？您使用的swagger-core版本是哪个？ - Ron

@Ron：是的，它有@Api(value = CLIENT_PATH, description = "客户端管理，如注册、读取、更新和删除")，并且它为其他方法生成文档，例如GET、DELETE。版本=1.3.12，artifactId=swagger-core_2.10。 - Jayaram

Answer 1

请查看您的index.html文件。该文件控制着哪些HTTP操作是交互式的。通过将其更改为下面的代码：

  window.swaggerUi = new SwaggerUi({
    url: url,
    dom_id: "swagger-ui-container",
    supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],

您将在PATCH方法上进行交互：

- fehguy

---

谢谢。在swagger-ui方面支持@com.wordnik.swagger.jaxrs.PATCH确实是一个修复措施，这里有两个问题，为什么自定义的Patch注释不起作用？由于我遵循Jsonpatch（RFC 6902），因此在发送请求的一部分作为主体时，我应该发送类似于此的内容“[{"op" : "replace","path" : "/message","value" : "patchedMessage"}]”，但这无法映射到资源，因此是否有任何修复措施？ - Jayaram

当我谈论自定义Patch注释时，就像这个网址https://github.com/jersey/jersey/blob/2.6/examples/http-patch/src/main/java/org/glassfish/jersey/examples/httppatch/PATCH.java - Jayaram

Swagger只扫描com.wordnik.swagger.jaxrs.PATCH，当我们编写它时，jersey中没有PATCH注释。如果您想支持自定义的patch行为，您必须在服务器上进行操作。现在添加两个注释(jersey和com.wordnik.swagger.jaxrs.PATCH)，它应该可以工作。我将添加一个票来添加对org.glassfish.jersey.examples.httppatch.PATCH的扫描支持。 - fehguy

谢谢，我已经添加了两个，并从自定义的一个中删除了 @HttpMethod("PATCH")。 - Jayaram

请注意，补丁支持已经提交，并将包含在1.5.2-M1中。 - fehguy