Skip to content

2025.1
Compare
Choose a tag to compare
@hauner hauner released this 01 Feb 17:06
v2025.1
8b73801

openapi-parser 3.0/3.1

bundling

OpenApiResult has a new bundle() method to bundle a multi-file OpenAPI document.

/**
 * Bundle the document, i.e. merge a multi-file document into a single file document. The bundled document has to
 * be parsed to navigate its OpenAPI model.
 *
 * @return a raw bundled copy of the OpenAPI document.
 */
@Experimental
Map<String, Object> bundle();

It can be used like this:

// kotlin
import io.openapiparser.model.v31.OpenApi
import io.openapiprocessor.jsonschema.reader.UriReader
import io.openapiprocessor.jsonschema.schema.DocumentLoader
import io.openapiprocessor.jsonschema.schema.DocumentStore
import io.openapiprocessor.snakeyaml.SnakeYamlConverter
import java.net.URI

"bundle example" {
    val loader = DocumentLoader(UriReader(), SnakeYamlConverter())

    // parse a multi file OpeAPI document (from resources)
    val originalDocs = DocumentStore()
    val originalParser = OpenApiParser(originalDocs, loader)
    val originalResult = originalParser.parse("/original/openapi.yaml")

    // bundle the OpenAPI, i.e. move $ref content to "components.schemas" and friends if the
    // ref points to a different file. The original document is not touched.
    val bundled = originalResult.bundle()

    // parse the bundled document (this creates a reference map for ref lookups) to navigate
    // its OpenAPI model.
    val bundledDocs = DocumentStore()
    val bundledParser = OpenApiParser(bundledDocs, loader)
    val bundledResult = bundledParser.parse(URI.create("/original/openapi.yaml"), bundled)

    val api = bundledResult.getModel(OpenApi::class.java)
    val summary = api.info.summary

    // We could use the same document store, but it would override the original (root) document
    // if we use the same id (in this case file name). We can use a different id to avoid that.
    //val bundledParser = OpenApiParser(originalDocs, loader)
    //val bundledResult = bundledParser.parse(URI.create("/bundled/openapi.yaml"), bundled)
}

writing an OpenAPI document

OpenApiResult has a new write(Writer writer) method to write a single-file OpenAPI document.

/**
 * Write the document. This will produce useful results only if the document is a single file document. Bundling
 * can be used to create a single file document.
 *
 * @param writer the target writer
 */
@Experimental
void write(Writer writer) throws IOException;

Based on jackson (io-jackson library) or snakeyaml (io-snakeyaml) an OpenAPI document can be written like this:

// kotlin
import io.openapiprocessor.jackson.JacksonJsonWriter
import io.openapiprocessor.jackson.JacksonYamlWriter
import io.openapiprocessor.snakeyaml.SnakeYamlWriter

// write an OpenAPI document. Use the alternative constructor to configure jackson or snakeyaml specific formatting.
val out = StringWriter()
val writer = JacksonYamlWriter(out)
//val writer = SnakeYamlWriter(out)
//val writer = JacksonJsonWriter(out)

openApiResult.write(writer)

updated dependencies

  • updated com.fasterxml.jackson:jackson-* to 2.18.2
Assets 2
Loading