Generating API documentation for vert.x based REST API
1,001 views
Skip to first unread message
Neeraj
Sep 7, 2017, 9:53:02 AM9/7/17
to vert.x
Is there any tool or framework using which I can generate API documentation for existing vert.x code.
Julien Viet
Sep 7, 2017, 12:08:11 PM9/7/17
to ve...@googlegroups.com
Hi,
you can get the API documentation in maven central with the -docs.zip artifact.
for instance:
it contains javadoc + asciidoctor documentation.
you can also get a zip of all HTML documentation (from Asciidoctor) on Bintray :
Julien
On Sep 7, 2017, at 3:53 PM, Neeraj <neer...@gmail.com> wrote:
Is there any tool or framework using which I can generate API documentation for existing vert.x code.
--
You received this message because you are subscribed to the Google Groups "vert.x" group.
To unsubscribe from this group and stop receiving emails from it, send an email to vertx+un...@googlegroups.com.
Visit this group at https://groups.google.com/group/vertx.
To view this discussion on the web, visit https://groups.google.com/d/msgid/vertx/1c943866-11e4-4741-9c58-591767a52691%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Neeraj
Sep 7, 2017, 12:16:19 PM9/7/17
to vert.x
Actually we needed something like swagger where we can test the api's too.
Julien Viet
Sep 7, 2017, 1:27:42 PM9/7/17
to ve...@googlegroups.com
ah it was not clear you wanted to do swagger like documentation for your own Vert.x application
To view this discussion on the web, visit https://groups.google.com/d/msgid/vertx/1fd36b6f-6e69-4965-be38-91be4c4a9f7b%40googlegroups.com.
Paulo Lopes
Sep 8, 2017, 4:54:55 AM9/8/17
to vert.x
Short answer, no!
Long answer, it's complicated!
Vert.x in contrast to say Spring is unopinionated, this means that everything that happens is explicitly written in code which renders automatic extraction of metadata a complex task. From a web router it would be possible to extract the base API endpoints with info such:
* http method
* endpoint
* accepts/produces mime-type
All the rest, e.g.: parameters, types of parameters, body type data is not possible, so such tool will only give you a bare bones skeleton.
If you're willing to take the opposite approach then you're way better served, with this year GSoC we had a project that can translate an OpenAPI definition to code and include all the required validation, see:
https://gist.github.com/slinkydeveloper/25e4f5543755480635b4dddc449dcf53
https://github.com/slinkydeveloper/vertx-web/blob/designdriven/vertx-web/src/main/asciidoc/java/index.adoc#validate-the-requests
Long answer, it's complicated!
Vert.x in contrast to say Spring is unopinionated, this means that everything that happens is explicitly written in code which renders automatic extraction of metadata a complex task. From a web router it would be possible to extract the base API endpoints with info such:
* http method
* endpoint
* accepts/produces mime-type
All the rest, e.g.: parameters, types of parameters, body type data is not possible, so such tool will only give you a bare bones skeleton.
If you're willing to take the opposite approach then you're way better served, with this year GSoC we had a project that can translate an OpenAPI definition to code and include all the required validation, see:
https://gist.github.com/slinkydeveloper/25e4f5543755480635b4dddc449dcf53
https://github.com/slinkydeveloper/vertx-web/blob/designdriven/vertx-web/src/main/asciidoc/java/index.adoc#validate-the-requests
jim-g...@spudsoft.co.uk
Dec 20, 2021, 3:16:58 AM12/20/21
to vert.x
What we do is use Jax-RS from within a Vertx-based application (with all the endpoints being asynchronous) using resteasy.
It's not very Vertxy, but it works and provides Swagger support.
Once you are beyond the first Jax-RS method you can be back in the world of Vertx, so we end up with things like this:
@GET
@Path("/getsomething")
@Produces(MediaType.APPLICATION_JSON)
@Operation(description = "Get something")
@ApiResponse(
responseCode = "200"
, description = "Something that has been got."
, content = @Content(
.serverError()
.entity(ex.getMessage()) // You don't really want to return raw exception messages to clients
.build()
It's not very Vertxy, but it works and provides Swagger support.
Once you are beyond the first Jax-RS method you can be back in the world of Vertx, so we end up with things like this:
@GET
@Path("/getsomething")
@Produces(MediaType.APPLICATION_JSON)
@Operation(description = "Get something")
@ApiResponse(
responseCode = "200"
, description = "Something that has been got."
, content = @Content(
mediaType = "application/json"
, schema = @Schema(implementation = Something.class)
)
)
public void getSomething(
@Suspended final AsyncResponse asyncResponse
, @Context Vertx vertx
, @QueryParam("arg") String argument
) {
, schema = @Schema(implementation = Something.class)
)
)
public void getSomething(
@Suspended final AsyncResponse asyncResponse
, @Context Vertx vertx
, @QueryParam("arg") String argument
) {
getSomethingUsingVertx
.onFailure(ex -> asyncResponse.resume(
Response.serverError()
.entity(ex.getMessage()) // You don't really want to return raw exception messages to clients
.build()
))
.onSuccess(result -> asyncResponse.resume(result));
}
}
This Jax-RS has void return type and the AsyncResponse is untyped so the Swagger processor needs to be told the data type that it's going to return.
Jim
deedarb
Dec 20, 2021, 3:45:06 AM12/20/21
to vert.x
Quarkus can be used as frontend (JAX-RS/GraphQL) for vertx service proxies,
quarkus is using vert.x, so it can join existing vert.x cluster.
it provides OpenAPI, GraphQL documentation generation.
Reply all
Reply to author
Forward
0 new messages