I want my Swagger output to have support for Protobuf and Websockets. (Protobuf is the most important)
Based on this issue, I don't think that swagger can support that. My goal is to allow end users to see the value of the Protobuf format since they are all asking me to use JSON instead.
I would contribute myself, but I'm unfamiliar with the swagger project at that level.
Question
Is there any way to get Swagger to support Protobuf or WebSockets?
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 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.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 4 years ago.
Improve this question
How can an event-driven microservices architecture be defined using the OpenAPI / Swagger specification? For events, it is important to document the event payload passed among different services, even when they are not accessed via HTTP paths.
Everything I've seen is API-based via HTTP paths, so I'm wondering now to implement this with OpenAPI / Swagger spec?
OpenAPI 3.1
OpenAPI Spec 3.1 supports events via the top level webhooks property. OpenAPI Spec 3.1 defines webhook support here:
Spec Definition: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md
Spec Example: https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.1/webhook-example.yaml
OpenAPI 3.0
For tools that handle OAS 3.0, defining event bodies using schemas only is still useful as such definitions can be used by codegen tools like OpenAPI Generator to auto-generate schema objects for languages like Java, Swift, Go, etc.
OpenAPI 2.0 / Swagger 2.0
For Swagger Spec 2.0 (aka OpenAPI Spec 2.0), you can include definitions in the Swagger spec as mentioned by alamar. Swagger Codegen will automatically create model classes for these definitions, even if they are not associated with any paths. I build and maintain a Swagger Spec/Codegen-built SDK in Go for the RingCentral API that has events like this. You can see the auto-generated classes/structs Swagger Codegen builds in the following folder, filtering for the 20 files that end in _event.go. These are currently created using swagger-codegen 2.3.1.
Generated files: https://github.com/grokify/go-ringcentral/tree/master/client
Codegen info: https://github.com/grokify/go-ringcentral/tree/master/codegen
If you have multiple event types, having an event property that can distinguish message types you are receiving can help parse it into the correct event class/struct. In Go, you can unmarshal the data twice, once into a generic struct to peek at the event type property, and then a second time for the actual event type.
I also maintain a collection of example events and parsing code in the Chathooks webhook reformatter project you can use for reference. You can see the example events and (hand-rolled) language definitions here:
Examples: https://github.com/grokify/chathooks/tree/master/docs/handlers
Definitions: https://github.com/grokify/chathooks/tree/master/src/handlers
AsyncAPI
An alternative to OpenAPI is to use AsyncAPI is a specification for event driven architectures. It is protocol agnostic so can be used with Kafka, Websocket, MQTT, AMQP and anything else based on messaging.
I think you can have definitions in Swagger even if they aren't used by any endpoints. Just declare any types that you need in a dedicated section, e.g. "definitions". You can refer ones that you're using in the endpoints as e.g. "$ref": "#/definitions/User", as per main Swagger live example.
I expect that code will be generated for them, so you can write tests against any of definitions.
If you have strongly typed events, you could use reflection to publish the structure of the events and that should be sufficient for a client of your microservice.
If you have some event descriptors (xml or similar) used to re-hydrate the events from the event store/event log then you can publish those.
Otherwise I don't know of any tools that would work like Swagger but for events.
If you are using Java, there is an alternative. I never tested this, but this idea could guide you for a solution for another platforms.
You can use the "good" and old Javadoc for that and the Swagger module from Enunciate, as explained here:
You can generate swagger-ui from Javadoc by using Enunciate, which has a Swagger module
It's just a maven plugin. In the final, you have a Full HTML documentation of your services, scraped from your JavaDocs..
im currently thinking how to build REST API docs for my application with support for multiple languages. Endpoints, parameter names and return values should stay the same but the description of each REST method i want to provide in different supported languages.
Im using Spring boot, data & rest and found this docs project what seems very useful to me. Anyway, i couldn't find any informations in the docs regards the i18n topic/support.
Does anybody know if Spring REST docs support the generation of the API doc for multiple languages (in general)?
REST Docs doesn't provide any out-of-the-box support for I18N but it should be pretty straightforward to build something on top.
The main piece with which REST Docs is involved and that I think you'd want to translate are the descriptions that are included in the various snippets. Rather than hard-coding a particular description, you could look each up in a ResourceBundle:
ResourceBundle resourceBundle = ResourceBundle.getBundle("field-descriptions");
mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andDo(document("example", responseFields(
fieldWithPath("a").description(resourceBundle.getString("a")),
fieldWithPath("a.b").description(resourceBundle.getString("a.b")))));