Fix OpenAPI Callback circe encoder

[seglo]

fixes #2095

Omits pathItems from being encoded into output JSON, similar to Encoder[Responses] and Encoder[PathItem]. Produces valid OpenAPI spec for callbacks.

The test is a big hack to add a callback, because it's not currently supported in the Endpoint DSL. I can drop that if you like.

[adamw]

Thanks!

But maybe the model is simply wrong? I mean the case class Callback itself. It should be a Map[String, PathItem], but without the wrapper? Question is, where do extensions go, and how references can be made.

Also, if you'd need a better api to add callbacks, let's simply add this to Operation for example.

[seglo]

Hi @adamw. I think you're right and the model is wrong. According to the Open API spec the callbacks field in an Operation object is defined as:

Map[string, [Callback Object](https://swagger.io/specification/#callback-object) | [Reference Object](https://swagger.io/specification/#reference-object)]

Where a Callback contains a single PathItem. It's basically a Map[String, PathItem] as you said.

An operation Callback can also reference re-usable callbacks defined in Components. I'm not sure how the reference relationship works, I'd have to dig into it more. The Callbacks page only includes an example of a callback defined within an Operation itself.

I can spend more time getting tapir's Open API model to encode the correct schema for callbacks, but I have some other priorities this week that I need to work on first.

Can you clarify what you mean with this statement:

Also, if you'd need a better api to add callbacks, let's simply add this to Operation for example.

Are you proposing extending Endpoint API to accept callbacks? This would certainly be an ideal outcome, but it would take me longer to implement. For my purposes I would be alright with the Open API model being encoded correctly.

[seglo]

Question is, where do extensions go,

I see now how the encoder in this PR is handling extensions and it's indeed incorrect. I don't think extensions belong at this level since it's supposed to represent a key/value mapping of callback names to callbacks. Extensions might be handled in the PathItem itself, the same way they're already done.

[adamw]

Are you proposing extending Endpoint API to accept callbacks? This would certainly be an ideal outcome, but it would take me longer to implement. For my purposes I would be alright with the Open API model being encoded correctly.

No, I think adding to Endpoint would be too niche, I though about some helper methods on the OpenAPI model classes, once you navigate to them from the generated value :)

[seglo]

No, I think adding to Endpoint would be too niche, I though about some helper methods on the OpenAPI model classes, once you navigate to them from the generated value :)

Got it. Works for me!

[seglo]

I think this solution is a little convoluted. I may be missing something with the design considerations in the OpenApi model.

The current implementation demonstrates adding callbacks to operations and components, as well as referencing a reusable callback.

How the test's expected yaml looks like generated with redoc:

[adamw]

@seglo we need to support multiple paths in callbacks, so I added the map back, changing the encoder. I also changed the test to use quicklens, I think it's more readable now :)

[seglo]

That looks much better, thanks. I had trouble adding quicklens to the project, but I see you were able to resolve that!