re: Defining reusable components with the OpenAPI specification VIEW POST

VIEW FULL DISCUSSION
 

Thank you for this post.

Currently I am working on a software project to develop a catalog of software tooling. As part of this project, I have developed a JSON Schema for describing tools. I want to avoid repeating myself, so I would like to incorporate this schema into my API contract which I am currently writing in OpenAPI 3.0. Do you think it would be problematic if I just incorporated the schema directly, even though I would be embedding a JSON Schema document into an OpenAPI document? What do you generally recommend for interoperability between the two?

 

If you can limit yourself to the common subset of JSON Schema draft 5 and OpenAPI 3.0 schema objects, you'll be fine. If that's a problem, take a look at speccy (github.com/wework/speccy) which implements a filter to convert JSON Schema to OAS schema objects, using github.com/wework/json-schema-to-o...

 

Another possible approach is to use the x-oas-draft-alternativeSchema extension (github.com/OAI/OpenAPI-Specificati...) although as this is brand new, we don't yet know of any implementations - so would probably only suit your own tooling.

code of conduct - report abuse