Feature request: Composed static OpenAPI documents

[pe-st]

While experimenting to prepare a talk (at Eclipsecon Europe 2019) I also tried a static file approach (design-first) with an OpenAPI document split in several parts (as explained in https://dev.to/mikeralphson/defining-reusable-components-with-the-openapi-specification-4077); code generation (with swagger-codegen or openapi-generator) works fine.

I would have liked to get the assembled document from the MicroProfile endpoint /openapi, but both Quarkus and OpenLiberty just return the part that still resides in the main openapi.yaml file (I didn't test with any other implementation).

The MP spec (section 4.2.1) doesn't really say something about multiple files yielding one final document, it just tells to not use multiple 'openapi.xxx' files with different extensions.

There are example projects with Quarkus (design-first-openapi-generator) and OpenLiberty (design-first-swagger-openliberty) in the feature/split branch of this GitHub repo: https://github.com/pe-st/apidocs/tree/feature/split, where I split the OpenAPI document in openapi.yaml and elements.yaml

It would be nice if a future version of the specification could address this feature.

[arthurdm]

thanks @pe-st

To help build some context on this area, can you please outline the value-add and use cases of having multiple static OAS3 snippets?

[pe-st]

@arthurdm I see two use cases

• maintainability during evolution of the OAS interface (for services with bigger interfaces one big openapi.yaml file can quickly become unwieldy, similar to programming where you like to split code into multiple classes and packages)
• reusability: let's say you have some basic models/schemas that you're using in multiple services. You could make some core-models.yaml snippet and use it in different services. Maybe you could even pull it in via dependency management (as an OAS snippet stored in a JAR that you pull in with Maven).

I'm not sure what workflows other people use, maybe they develop their OAS document outside the service? I currently evolve my services' interface directly in the services' workspaces and repos, and would welcome a more modular approach for OAS documents.

[EricWittmann]

Overall I agree with this approach to designing the API - it's often vital to be able to e.g. re-use types across multiple API designs. I'm not sure whether it makes sense to support that in MP OpenAPI or whether the assumption is that the content should be normalized first. I tend to think you're right - the spec could support multiple files for a modular design and it would be quite nice. Right now that's a bit at odds with how the spec is written. Need to discuss it to see what is possible. Good topic for the next hangout.

[arthurdm]

We agreed on the hangout yesterday that this is a good idea - thanks for the sample @pe-st, it helped to illustrate the scenario.

One concern we all share though is related to collisions. The spec will likely need to state that is up to the user to ensure the snippets to not have colliding elements, as the behaviour will be unspecified.

[bmarwell]

One concern we all share though is related to collisions. The spec will likely need to state that is up to the user to ensure the snippets to not have colliding elements, as the behaviour will be unspecified.

You can already have collisions in other scenarios, no? I would just print out a warning and use the first or last one (just use assumptions until the spec defines it). The warning could include a notice that the behaviour could change in the future and is not stable.

If there is no collision, which is probably 99% of the cases, we can just proceed ahead.

My openapi.yaml file is already very long. I would be happy to see this soon!