OpenAPI v3 object model

The object model for OpenAPI v3 specification documents.

Licensing

This library ships under the SPDX-License-Identifier: Apache-2.0.

FAQ

• What does this do?

1. This package knows how to marshal and unmarshal OpenAPI v3 specifications into a golang object model
2. It knows how to resolve $ref and expand them to make a single root document

• How does it play with the rest of the go-openapi packages ?

1. This package is at the core of the go-openapi suite of packages and code generator
2. There is a spec loading package to fetch specs as JSON or YAML from local or remote locations
3. There is a spec validation package built on top of it
4. There is a spec analysis package built on top of it, to analyze, flatten, fix and merge spec documents

• Does this library support OpenAPI 3?

Yes! This package now supports OpenAPI v3.x (specifically OpenAPI 3.0+). The codebase has been migrated from OpenAPI v2 (Swagger 2.0) to OpenAPI v3.

Key changes in v3:

• swagger: "2.0" → openapi: "3.x.x"
• definitions, parameters, responses → components/*
• host, basePath, schemes → servers[]
• Body/form parameters → requestBody
• Response schemas → content with media types

For migration guidance, see MIGRATION_V3.md

• Does the unmarshaling support YAML?

Not directly. The exposed types know only how to unmarshal from JSON.

In order to load a YAML document as a Swagger spec, you need to use the loaders provided by github.com/go-openapi/loads

Take a look at the example there: https://pkg.go.dev/github.com/go-openapi/loads#example-Spec

See also go-openapi#164

• How can I validate a spec?

Validation is provided by the validate package

• Why do we have an ID field for Schema which is not part of the swagger spec?

We found jsonschema compatibility more important: since id in jsonschema influences how $ref are resolved. This id does not conflict with any property named id.

See also go-openapi#23