search

swagger-api / swagger-core

Examples and server integrations for generating the Swagger API Specification, which enables easy access to your REST API
http://swagger.io
Apache License 2.0
7.37k stars 2.17k forks source link

swagger-servlet - allow path customization #1823

Open zyro23 opened 8 years ago

zyro23 commented 8 years ago

using swagger-servlet-1.5.9.

1678 which "fixed" #1512 made swagger-servlet use the method names as path (not the nickname, which is ok).

but now it seems there is no option at all anymore to supply a custom path for an operation. it would be great if customization of an operation path is possible (independent from its method name).

DerEineDa commented 8 years ago

I second this request! I can't even imagine that the current state is the expected behavior.

We are using Jetty, so all operations would currently have the path "/handle" (for Jetty handlers) or "/doGet" or "/doPost" (for servlets), as these are the methods names for handlers and servlets. To avoid this, for each operation I currently have to create a second method with the intended name that only exists for its name and to carry the @ApiOperation and @ApiImplicitParams annotations.

If I already have to create methods that only exists for the purpose of generating the swagger specification, I fail to see the purpose of the @ApiImplicitParam annotations, as I could just add actual java parameters to the "only for swagger documentation"-methods and annotate them with @ApiParam annotations. Unfortunately, the "Reader" class for servlets currently doesn't parse @ApiParam annotations.

Another problem with the current state is that it is complicated to create two operations with the same path but with different HTTP methods. As the java methods must have the same name, I currently have to put the methods for GET and POST into different classes (or make them have different parameter overloads, which is even more hacky).

Do I miss something here? Is there a better solution or are all operations supposed to have the same name?

DerEineDa commented 8 years ago

Also, currently @Api.value() becomes part of the path, which shoudn't happen, as stated by the JavaDoc:

In swagger-core 1.3.X, this was used as the 'path' that is to host the API Declaration of the resource. This is no longer relevant in swagger-core 1.5.X.

DerEineDa commented 8 years ago

Sorry, me again.

The sample at https://github.com/swagger-api/swagger-samples/blob/master/java/java-servlet/src/main/java/io/swagger/sample/servlet/SampleServlet.java seems outdated. It uses both @Api.value() (which shouldn't be used, see above) and @ApiOperation.nickname() (which doesn't work anymore, see first comment) to set the path of the operation.

Because of this, the unit test at https://github.com/swagger-api/swagger-samples/blob/master/java/java-servlet/src/test/java/io/swagger/sample/ResourceListingIT.java currently fails at the line

Assert.assertNotNull(swagger.getPath("/sample/users/getUser"));

DerEineDa commented 8 years ago

The method name is also used as the unique operationId, but that doesn't make sense, as the method name is always the same for servlets. Because of this, @ApiOperation.nickname() is pretty much mandatory to set, because the default is guaranteed to lead to non unique operationIds.

fehguy commented 7 years ago

This should be fixed as of 1.5.10. Please test and reopen if needed.

zyro23 commented 7 years ago

not fixed in 1.5.10 and 1.5.12.

so as of 1.5.12, there is no way to customize path and/or operationId.

i got only a comment button, could you please reopen (dunno if reopening has somehow been disabled)?

rajajain commented 7 years ago

Is it going to be fixed in next release as we are also facing same issue.

fehguy commented 7 years ago

Yes, in the next major release as this is will be a breaking change.

zyro23 commented 6 years ago

please note that it seems @ApiOperation.nickname is used as path from swagger-core-1.5.14 on (ref. https://github.com/swagger-api/swagger-core/commit/5d13697fe715e488068ec173f4dd902753c0524a).

but as @ApiOperation.nickname is also used as operationId, this still causes duplicate ids for endpoints with different methods having the same path (https://github.com/swagger-api/swagger-core/blob/v1.5.17/modules/swagger-servlet/src/main/java/io/swagger/servlet/extensions/ServletReaderExtension.java#L232).

also, the 1.5.14 change referenced above has not (yet?) landed on the 2.0 branch (https://github.com/swagger-api/swagger-core/blob/2.0/modules/swagger-servlet/src/main/java/io/swagger/servlet/extensions/ServletReaderExtension.java#L218).

as there has been a change in a non-major release now, it would be great if we could fix this and restore consistency across the release branches as well.

thank you!