search

softwaremill / sttp-apispec

OpenAPI, AsyncAPI and JSON Schema Scala models.
Apache License 2.0
23 stars 11 forks source link

Extend the openapi model with helper/builder classes/methods #4

Open adamw opened 5 years ago

adamw commented 5 years ago

The goal is to create an API for working with the OpenAPI model so that it would be feasible to define a single PathItem (endpoint) "by hand". While the goal of tapir is for most of the endpoints to be defined as tapir.Endpoint, there will be for sure cases where a manually-defined endpoint will be necessary. The openAPI API will allow creating documentation for these endpoints in a humane way.

ghostbuster91 commented 5 years ago

I think that when we extend tapir model to fully support all the open api cases there will be no need to create open api objects in a different way than converting from tapir.

adamw commented 5 years ago

Yes and no. I doubt we'll be able to support all the details that can be captured in the openapi model. Plus, there always might be "special" endpoints, which can't be described by tapir (e.g. if you want to use some low-level api of akka-http or http4s). In this case, for these special endpoints, you can always fall back to use the "raw" API and define the missing documentation using the programmer-friendly builder methods

ghostbuster91 commented 5 years ago

I agree that you might not want to use tapir to create an http4s implementation for you. But despite the complexity of such hand crafted implementation it will still be a function on some high level of abstraction which takes some input and returns some output which tapir already can do. (And you will only use this tapir definition to derive openApi structure from it)

Supporting full open api model is another story and I am afraid that you may have right in that matter.

adamw commented 5 years ago

@ghostbuster91 ah, you are right, you might simply use the tapir api only to generate docs :) And then, refine this model further with openapi-specific details.