Is there a way to add description to the generated swagger code?

[josephmak]

Thanks for the jaxrs-analyzer... it is able to go inside my code and generate swagger json... is there a way to generate a comment for the method? I mean a "summary" or "description". Is there any special annotation or something inside javadoc?

[rmpestano]

Hi @josephmak,

A javadoc comment on the JaxRS endpoint should do the trick, same for endpoint parameters, ex:

/**
     * Deletes a car based on its ID
     * @param user name of the user to log in
     * @param id car ID
     * @response 401 User not authorized
     * @response 403 User not authenticated
     */
    @DELETE
    @Path("/{id:[0-9][0-9]*}")
    @RestSecured
    public Response deleteById(@HeaderParam("user") String user, @PathParam("id") Integer id) {
        Car entity = carService.findById(id);
        if (entity == null) {
            return Response.status(Status.NOT_FOUND).build();
        }
        carService.remove(entity);
        return Response.noContent().build();
    }

generates following swagger.json here:

 "delete": {
    "description": "Deletes a car based on its ID",
        "consumes": [
        ],
        "produces": [
        "application/json;charset=utf-8"
        ],
        "parameters": [
        {
        "type": "integer",
            "name": "id",
            "in": "path",
            "required": true,
            "description": "car ID"
    },
    {
        "type": "string",
            "name": "user",
            "in": "header",
            "required": true,
            "description": "name of the user to log in"
    }
    ],
    "responses": {
        "204": {
            "description": "No Content",
                "headers": {
            }
        },
        "401": {
            "description": "User not authorized",
                "headers": {
            }
        },
        "403": {
            "description": "User not authenticated",
                "headers": {
            }
        },
        "404": {
            "description": "Not Found",
                "headers": {
            }
        }
    },
    "tags": [
        "cars"
        ]
}

I'm using v0.17 of the analyzer.

[josephmak]

Thank you!