I would like to document the gRPC API in my Spring Boot application. The sources on the web that I have looked through suggest something like mapping endpoints to REST and then generating documentation (e. g. Swagger). I would like to find out if there is a simpler way (without REST) to document gRPC endpoints (something like Swagger), to be able to "automatically" generate the documentation if some changes occur.
Related
My project uses different protocols to communicate with other services:
REST API
WebSocket (STOMP)
gRPC
own framework build over gRPC.
I need a tool, or a bunch of tools, which allow me to generate documentation for the APIs. In the best scenario, it's a maven plugin that generates a report with all APIs.
We use Swagger to describe the REST API. It has poor export options and needs a lot of annotations in the code, but describes the API well and offer the test machine.
Alternatively, Spring RestDocs (AsciiDoctor) could be used for the REST API describing. It offers a better format for reporting, but we prefer Swagger.
That's all I found for the REST API. But I didn't find anything for describing WebSocket API, gRPC and the custom framework.
I will be very grateful for any help and ideas to solve the problem.
I have a Ktor application (in Kotlin) and would like the endpoints to be exposed according to the JSON:API specification. I understand my library options are between the Java server libraries for JSON:API, i.e. Katharsis (which gives code examples for Dropwizard, Spring Boot etc.) and Crnk (which gives example for Spring Boot). I have tried a bit with Katharsis but it's not clear to me how the ResourceRepositoryV2 class should be registered/exposed by the Ktor application.
Any examples or pointers?
The functions for operating the restful api is quite same. Is there any project that can generate the source code for different platform such android,ios and backend stuff.
I suggest you to use API description languages such Swagger ou RAML.
After having described your RESTful application with a language like this, you will be able to generate things like server skelekons and client sdks with different technologies and languages. You can even generate documentations.
With Swagger, swagger-codegen will do that. swagger-ui may also interest you for the documentation part.
To finish, I would like to mention the Restlet studio that allows to define graphically and quickly the structure of RESTful applications and generate then the corresponding Swagger and RAML contents. The APISpark plaform provides a mecanism to introspect Restlet applications and generate the corresponding contents with these languages. It also allow you to generate a set of server skelekons and client sdks.
Hope it helps you.
I will suggest you to use Spring RESTful webservices starter kit. Which will manage your back-end with centralized database. Also Spring has its own android libs to communicate with REST Apis.
okay you might say its a duplicate of this.
It might be but the answer is still yet to be found.
Isn't there any way we can make a RESTful web service without using jersey or for that matter any other libs?
I am searching for the past 5 days for the answer to this question!!
You should be able to accomplish this with servlets.
Create a servlet for each service or url that you expose to your service consumers.
Eg. For a user CRUD service, create a UserServlet and specify the mapping as /user/*.
Consumers of your service, will hit urls such as
http://yourdomain.com/user
http://yourdomain.com/user/23
for various RESTful operations.
Inside of the servlet, you should be able to extract the request parameters, form data, request headers and context information.
For a detailed discussion on how to design your restful api and best practices, search "Restful API Design". Here are a couple of links to get you started
https://blog.apigee.com/detail/api_design_third_edition_video_slides
https://blog.apigee.com/detail/slides_for_restful_api_design_second_edition_webinar/
If you want to use JAX-RS, which is a specification, you must use an implementation of this specification. Jersey is the Reference Implementation of JAX-RS but any other implementation is fine, too.
You can write a service with a RESTFul interface using plain Servlets. But why reinvent the wheel? You really don't want to do this. But if you must, read the Java EE Tutorial on Servlets. But a Servlet will not be RESTFul without further work. You can easily fall into the trap of writing a RPC-style service.
The RESTful Web service APIs are implemented using Restlet. I need to generate the API documentation for these. Rather than starting with a separate document, I am evaluating if this can be generated from the source code annotations itself.
I looked at Swagger and enunciate. Swagger seems to be based on the JAX-RS specification. Enunciate looked a little more promising as there is an FAQ that mentions how to generate for non JAX-RS implementations but there is no help.
Are there any tools (or if the community has used any) for generating API documentation from Restlet annotations?
Has anyone integrated Restlet with enunciate for generating documentation?
Restlet now supports the ability to generate either corresponding Swagger and RAML contents based your application at runtime.
Following docs could help you:
For Swagger (extension org.restlet.ext.swagger): see http://restlet.com/technical-resources/restlet-framework/guide/2.3/extensions/swagger
for RAML (extension org.restlet.ext.raml): see http://restlet.com/technical-resources/restlet-framework/guide/2.3/extensions/raml
You can then leverage tools from the tool community to generate your API documentation. You could consider Swagger UI that is a great tool to display online what an API provides and interact with it.
Hope it helps you,
Thierry