I have an API generated from protobuf, and I would like to generate documentation conforming to the OpenAPI 3 spec. I've looked at a number of utilities but I haven't found a combination that works.
Does anyone know of a path from protobuf to OpenAPI 3 that I can follow?
I searched for the answer recently and found this package:
protobuf2swagger
It can be run in CLI with a js config file required. This packaged solved my problem.
Google has a repository on GitHub to do exactly that. It contains examples for OpenAPI v3 (and v2) on how the equivalent protobuf code should look like.
Here is a medium article that explains end to end gRPC + HTTP (using protobuf and swagger respectively) server implementation and documentation, in a step by step fashion. It is an OpenAPI v2 example, but similar concepts apply to OpenAPI v3.
There are other repositories that can do the same, but I would recommend to use the source code that is actually coming from the very source. :)
Hope this helps!
Looks like protoc-gen-openapi app, from gnostic, is what you were looking for. But it seems abandoned and not working.
Have no idea if it works.
Related
Is there a way to generate OpenAPI spec files from a gin project? This issue is really hard to search for, all I could find so far are on doing there reverse.
gin-swagger is extracting comments from your code.
Running swag init generates :
docs.go: To serve SwaggerUI pages
swagger.json: The Swagger Specification in json file format.
swagger.yaml: The Swagger Specification in yaml file format.
You mean API docs for API user?
I saw you tag the question with swagger.
You have two chooses:
go-swagger
This package contains a golang implementation of Swagger 2.0 (aka OpenAPI 2.0): it knows how to serialize and deserialize swagger specifications.
swag
Swag converts Go annotations to Swagger Documentation 2.0. We've created a variety of plugins for popular Go web frameworks. This allows you to quickly integrate with an existing Go project (using Swagger UI).
What difference between them?
Here is the answer from go-swagger:
The main difference at this moment is that this one actually works...
The swagger-codegen project (like swag) only generates a workable go client and even there it will only support flat models. Further, the go server generated by swagger-codegen is mostly a stub.
Detail of this answer in How is this different from go generator in swagger-codegen?
from go-swagger.
For my springboot project, I am using OpenAPI 3.0.3 and springfox(3.0.3) for API documentation. I would like to generate the API documentation in YAML format, not JSON. By default, springfox generates JSON.
I have looked into using springdoc-openapi-ui instead of springfox (springdoc has the option of YAML format), but then I have to change all annotations and so on.
I was wondering if there is a way around it for telling springfox to generate yaml instead of json.
Thank you!
There is already a github issue with this query. Check out the discussion here for various possibilities -> https://github.com/springfox/springfox/issues/985
Another approach could be to take Springfox JSON and convert it to YAML using JSON2YAML converter as in https://www.json2yaml.com/.
I found a pretty neat link to host yaml files in Swagger UI here, but it uses Springfox instead of Springdoc so I would like to know if there is any other equivalent way of doing it since my company would prefer the latter.
I would really appreciate any help, just a guide is fine.
You can watch this project. As I understand it, they can use static content.
You can have a look at the documentation:
https://springdoc.org/faq.html#what-is-a-proper-way-to-set-up-swagger-ui-to-use-provided-specyml
I am new to Spring-Boot. I want to auto generate my REST api documentation into RAML from my Spring MVC controllers. Is there anything to do that? or any guide that I could use it for generating my rest api into RAML?
There is a Spring REST Docs to RAML extension for Spring REST Docs: https://github.com/ePages-de/restdocs-raml However, this project is not maintained anymore and the authors recommend to use their new project https://github.com/ePages-de/restdocs-openapi that converts to OpenAPI (Swagger) instead of RAML. They provide a guide on how to convert OpenAPI to RAML: https://github.com/ePages-de/restdocs-openapi#convert-to-raml There is an example project that demonstrates the conversion to OpenAPI and RAML https://github.com/ePages-de/restdocs-openapi/tree/master/samples/restdocs-openapi-sample One limitation of the extension is that it only works with Gradle at the moment.
I know, your Question is outdated, but there is something that might help.
You can use DocDog. From there it creates RAML from the existing source code. If it is SpringBoot you can run it easily with -lang=spring. If it is plain JAVA you can add comments to your code (see readme.md or examples), so DogDoc can understand.
May it helps you: https://github.com/skalski/docdog
I am starting to use Spring REST Docs but I miss a nice feature of swagger... the "try it out!" button that includes a HTML form to test the API. I get the curl link OK; but I usually use swagger form.
Is there a simple way to do this in Spring REST Docs?
Thanks
I solved it for myself by creating a tool to convert Spring REST Docs cURL snippets to Postman collections. It's available as a npm package: https://www.npmjs.com/package/restdocs-to-postman that can be used on the command line and as a library. This is one solution for https://github.com/spring-projects/spring-restdocs/issues/47. In my opinion tools like Postman are good to try out APIs.
Edit: There are converters from Postman and Insomnia to Swagger. So with two conversions (restdocs to Postman/Insomnia and Postman/Insomnia to Swagger) one can get a Swagger playground. This is not optimal, but works.
Examples for converters:
Postman to Swagger: https://apimatic.io/ (paid service with trial)
Insomnia to Swagger: https://github.com/mlabouardy/swaggymnia (MIT license)
Edit 2: I have created instruction on how to create a Swagger playground out of Spring REST Docs: https://github.com/fbenz/restdocs-to-swagger It takes a few steps and would be simpler if Spring REST Docs would directly produce a Swagger file, but it works and can be automated.
No, the closest I believe it can provide is a curl with an example request. There is an open enhancements to provide Postman collections, https://github.com/spring-projects/spring-restdocs/issues/47, but nothing as simple as Swagger's try it out!
Also somewhat related from this ticket, https://github.com/spring-projects/spring-restdocs/issues/213,
I'm rather torn on trying to add support for generating a Swagger specification. When you describe Swagger as providing an "API Playground", you've drawn a very important distinction that many others do not. I firmly believe that Swagger's UI is not a substitute for API documentation and using it as such isn't good for a service or its users.
My fear is that if Spring REST Docs provided support for producing a
Swagger specification, people would then use that specification to
populate Swagger's UI and consider their service to be documented.
It's a matter of weighing up trusting people to do the right thing,
versus encouraging people to shoot themselves in the foot.