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.
Related
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 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.
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
Is it possible to generate a Swagger documentation for my ASP.Net Web API in a separate project?
I created an empty project where the Swagger documentation should go. In the API project the Swagger project is referenced, but didn't work.
Than API project is load like an external assembly. The controllers was reachable, but documentation wasn't generated.
Then tried with the automatically generated XML documenatation, just to see if it will create anything, but there is no result.
After this try like to have multiple API in one Swagger documentation, Multiple API documentation in one Swagger file, wasn't work.
I also tried this:
ApiExplorer for WebAPI controllers in external assembly
https://github.com/Microsoft/aspnet-api-versioning/issues/271
On the Swagger official documentation I didn't find something that could help me with this. Neither did I find any information elsewhere if this is possible and how it needs to be done.
I use Swashbuckle 5.6.0 and ASP.Net Web API.
Yes, it is possible to generate Swagger documentation for a Web API in a separate project.
Here I have the code showing how I did it:
https://github.com/heldersepu/csharp-proj/tree/master/Swashbuckle.Sample
And here is how the swagger-ui looks like:
http://swashbucklesample.azurewebsites.net/swagger/ui/index
To be honest Nothing special about that code, it worked on the first try for me ...
But I do have some experience with Swashbuckle
If you can provide a minimal project reproducing your issue, we can help you get to the bottom of it together.
There is a number of good documenting tools for Django REST Framework, especially Django REST Swagger: http://www.django-rest-framework.org/topics/documenting-your-api/
All of them are for online usage. Is there a tool to generate offline documentation: PDF or a collection of HTML/CSS-files? Something like http://sphinx-doc.org/ does?
Assuming you've the Swagger spec file (JSON/YAML), you can use Swagger-Codegen to generate the static documentation for your REST API.
UPDATE: On May 2018, about 50 top contributors and template creators of Swagger Codegen decided to fork Swagger Codegen to maintain a community-driven version called OpenAPI Generator. Please refer to the Q&A for more information.