Parses and serializes OpenAPI JSON files into data classes, handling union types and x- properties efficiently. Offers easy integration and usage within projects.
A Kotlin Multiplatform library that provides bindings for OpenAPI JSON files. The library can parse and serialize OpenAPI specifications to Kotlin data classes, handling union types and x-properties (extensions).
Table of Contents
Features
Support for OpenAPI 3.0, 3.1, and 3.2 — selected automatically by the openapi version string
Support for OpenAPI v2 (Swagger) specifications
Kotlin Multiplatform support (JVM, JS, Native)
Serialization and deserialization of OpenAPI JSON
Strict typed bindings: unmodeled keywords throw rather than silently drop
Proper handling of union types
Support for x-properties (extensions)
Type-safe Kotlin data classes for OpenAPI models
Supported Platforms
JVM
JavaScript (NodeJS)
Native
macOS (x64, arm64)
Linux (x64)
Windows (x64)
Installation
Add the dependency to your build.gradle.kts or build.gradle file:
OpenAPIV3 is the single entry point for 3.0.x, 3.1.x, and 3.2.x. It reads the
openapi version string and returns a sealed OpenAPIV3Model whose variant
(OpenAPIV30Model / OpenAPIV31Model / OpenAPIV32Model) carries the
version-specific fields typed.
OpenAPIV2 mirrors the V3 shape for consistency: it reads the swagger
version string and returns a sealed OpenAPIV2Model whose variant
(OpenAPIV20Model) carries the version-specific fields typed. Today
only Swagger 2.0 is published, so there is one variant; the sealed
shape leaves room for future minors without breaking the public API.
The library automatically handles x-properties (extensions) in OpenAPI specifications. These properties are stored in an xProperties field during parsing and are restored when serializing back to JSON.
Breaking changes from 0.1.x
The 3.1 / 3.2 support release breaks the OpenAPI v3 surface (the library is still pre-1.0). Specifically:
The OpenAPI 3.1/3.2 keywords that are modeled (and roundtrip losslessly):
// Encode roundtrips through the sealed interface.
val
OpenAPIV3Model and OpenAPIV2Model are now sealed interfaces. Reads against either still compile; instantiation and copy() move to the per-minor data classes — OpenAPIV20Model, OpenAPIV30Model, OpenAPIV31Model, OpenAPIV32Model.
Version.V2 and Version.V3 are replaced by Version.V20, V30, V31, V32, with Version.fromSwaggerString and Version.fromOpenApiString parsers.
OpenAPIV3.decodeFromString and OpenAPIV2.decodeFromString now dispatch by version string. A 3.1.0 document previously decoded into the same data class as 3.0 (silently dropping 3.1-only fields); it now decodes into OpenAPIV31Model and surfaces those fields typed.
Schema.exclusiveMinimum / Schema.exclusiveMaximum are no longer on the shared Schema interface.OpenAPIV30Schema has them as Boolean? and OpenAPIV31Schema / OpenAPIV32Schema as Double? — matching each version's spec.
OpenAPIModel.paths is now nullable (3.1 made it non-required). All concrete V3 subclasses' paths are nullable too; OpenAPIV20Model.paths stays non-null because Swagger 2.0 requires it.
All OpenAPIV2X type names are renamed OpenAPIV20X (Schema, Reference, Parameter, etc.). The directory layout moved files under v20/, v30/, v31/, v32/ but the Kotlin package stays flat as community.flock.kotlinx.openapi.bindings.
Strict mode is unchanged for 2.0 and 3.0 docs; for 3.1/3.2 it newly rejects unmodeled JSON Schema 2020-12 keywords ($id, $anchor, $dynamicRef, $dynamicAnchor, $schema, $comment). If you hit one in the wild, please open an issue.
