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..
Related
I can run a Spring Boot application and then use the springdoc-openapi-maven-plugin artifact to generate an OpenAPI spec.
However, is there also a way to generate the spec without running the application first?
I currently want to generate the spec in a GitHub Action and a direct way would simplify this a lot.
you can use swagger editor: https://editor.swagger.io/
It allows you to write a json/yaml with your specifications and at the same time you can view the result.
Also, in the upper part there are 2 features, which allow you to generate the code based on the json/yaml made.
For example you can create a spring application with all the endpoints you go to specify in your json/yaml ( server).
But you can also generate HTML. (Client)
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.
I am working on a project that is trying to use the polled consumer API. However, existing documentation, blog posts and sample code seems to use deprecated annotations (such as org.springframework.cloud.stream.annotation.Input). This seems to be because they are relying on the older style of Spring Cloud stream applications rather than using Java functional api (e.g., java.util.function.Function), as shown in other examples such as this one, given in the same repo.
Is there a way to use functional style with polled consumers in Spring Cloud Stream?
You are using outdated documentation. The most current is available from the project site - https://spring.io/projects/spring-cloud-stream#learn.
The section you are looking for is - https://docs.spring.io/spring-cloud-stream/docs/3.1.5/reference/html/spring-cloud-stream.html#spring-cloud-streams-overview-using-polled-consumers
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?
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.