Use Goa DSL to define OpenAPI 3.0 Callbacks

[cpatsonakis]

Hello!

OpenAPI 3.0 allows the definition of Callbacks, i.e., requests that the service will perform when the an external client invokes one of its endpoints.

I am reasonably familiar with Goa's DSL (not a wizard by all means), but I can't figure out a way of using the DSL so that the generated OpenAPI specification of a service reflects such functionality (and by extension to the generated code). Is there a way to do this in the current version of the DSL?

I see a CallbackRef type definition in the DSL's code generation package, but I have no idea if it's reachable from the DSL's API, or this just exists there as a placeholder for the future?

Any ideas or perhaps examples that you can point me towards?

Thank you very much!

[raphael]

Hello!

There is indeed no support in the Goa DSL for OpenAPI 3.0 callbacks at this point but this would make a great addition. There would probably need to be a new DSL function that makes it possible to list callbacks that would live under the method HTTP function:

Method("subscribe", func() {
    Payload(func() {
        Attribute("CallbackURL", String, "Callback URL", func() {
            Format(FormatURI)
        })
    })
    Error("gone", "Error sent by client to stop callback requests")
    HTTP(func() {
        POST("/")
        Callback("ready", func() {
            CallbackURL("{CallbackURL}") // CallbackURL accepts a Path like string that can reuse body payload attributes
            Body(ReadyEvent) // ReadyEvent is a user type
            Response(StatusOK, func() {
                Body(ReadyEventResponse) // So is ReadyEventResponse
            })
            Response("gone", StatusGone)
       })
       Callback("failed", func() {
           // ...
       })
})

This DSL would update the generated OpenAPI specification to reflect the callbacks. The nice thing is that this wouldn't affect the server or client generated code.