One can document a REST API with OpenAPI. Is there a similarly clean and standardized way of documenting gRPC APIs? E.g. specify what values an endpoint is expecting, what the return values mean, etc. The service definitions in a .proto file do not suffice as documentation.
I just found this: https://gendocu.com/
which let you try your APIs and document the fields. Also generates code for different languages. The project looks promising.
Related
I have one project in aws lambda in Golang.
There we are using aws-api-gateway to accept rest api.
I wanted to sort the xml payload based on element coming from the user side.
But the problem is unmarshalling the xml payload is not allowed.
I see somewhere that I can use xslt processor to sort the xml. But I’m unable to use this go package(github.com/wamuir/go-xslt) as it requires me to install some extra packages which is not in go. And our platform-team will not allowed it.
Is there any other go package that I can use.
since google did not create extensive documentation for their API Linter and I cannot find anything from other sources, i wanted to ask here.
From what exactly am i supposed to create protofiles and what do they represent?
As I understood, these protofiles get checked for compliance to their AIPs.
I'm interested in creating a automatic prototype (Java) to check for customized API Rules and am thinking about using Protobufer for this goal. Would this be a pragmatic solution?
Thank you!
As I now understand, Googles API Linter isn't supposed to check a API or a different API specification for compliance.
It checks proto files because they are themself the API specification and can be converted to Code. But before converting them they can be checked against rules they have to comply with.
These rules are not in the protofiles (as I initially thought) but in the many GO-files under rules/ .
Please correct me if you read this and find mistakes! Thanks!
Does gRPC support generating documentation for services like Swagger?
protoc-gen-doc is a protoc plugin which generates HTML docs using Go HTML templates. Although it isn't being used by the original sponsor company anymore, it looks like a good starting point.
Your protofiles are the documentation.
You can put comments there to clarify meaning of parameters or service methods.
We all know that apiary rocks (or not.. I think it does), and I was wondering what would it take to take it a step further allow users to export a JSON description of the API? (So developers can script client code generation)
This should help:
http://ttezel.github.io/blog/2013/02/23/stop-writing-rest-api-clients/
There are two directions you can explore:
you can use Alpaca to generate client SDKs. Alpaca accepts API Blueprint as one of it's input formats
for more flexibility, you can use Snowcrash to parse API Blueprint into JSON - and roll your own code generator.
There are more tools around API Blueprint available at http://apiblueprint.org/
What is the best approach to version WebAPIs?
I am building an API from scratch and I would like to ensure that it will version gracefully in the future. I am envisioning something like mysite.com/api/v2/...
One approach I see is to create a separate project (web app) for each version of API. But perhaps there are better ways to do it?
Thank you for your ideas.
Including version number in the URL is the standard approach as I explained in this post (I do not repeat the content): Implementing versioning a RESTful API with WCF or ASP.Net Web Api
You do not need to create a completely new project although you can. The problem that you will be facing with a single project is that there will be collision of names:
/api/v1.0/Car/123
and
/api/v2.0/Car/123
both will point to CarController while you can have only one of those. The solution would be to implement your own IHttpControllerSelector and register with the DependencyResolver. This implementation will look at the version number and perhaps find the type based on the namespace.
UPDATE
I do not intend to start a REST controversy here. But as #DarrelMiller points out, here is an older discussion on the same subject discouraging my suggested approach:
How to version REST URIs
I personally think URL versioning is the way to go.
You will need to create your own implementation of IHttpControllerSelector. The best way is to base this implementation on Microsoft's IHttpControllerSelector. Then you can decide in your IHttpControllerSelectorif you want to version by URL or by content-type.
The most basic implementation directly implements IHttpControllerSelector and just implements the SelectController method but performance reasons it is better to implement some caching around it.
For finding the Controller you simple the IHttpControllerTypeResolver instance you can get using HttpConfiguration.Services.
I've used something like this: http://damsteen.nl/blog/implementing-versioning-in-asp.net-web-api. Also put some code on Github: https://github.com/Sebazzz/SDammann.WebApi.Versioning.