sv-tools/openapi

OpenAPI v3.1 Spec implementation in Go with generics

OpenAPI v3.1 Specification

The implementation of OpenAPI v3.1 Specification for Go using generics.

Supported Go versions:

• v1.22
• v1.21
• v1.20

Versions:

• v0 - Deprecated. The initial version with the full implementation of the v3.1 Specification using generics. See v0 branch.
• v1 - The current version with the in-place validation of the specification. The minimal version of Go is v1.20 and the github.com/santhosh-tekuri/jsonschema/v5 package is not used anymore. See main branch.

Features

• The spec folder contains full implementation of the v3.1 Specification using generics and errors.Join function, so the minimum supported version of Go is v1.20.
• The spec.ValidateSpec function validates the specification without transforming it to map[string]any.
• The official v3.0 and v3.1 examples are tested. In most cases v3.0 specification can be converted to v3.1 by changing the version's parameter only.

  @@ -1,4 +1,4 @@
  -openapi: "3.0.0"
  +openapi: "3.1.0"

NOTE: The descriptions of most structures and their fields are taken from the official documentations.

Links

• OpenAPI Specification: https://github.com/OAI/OpenAPI-Specification and https://spec.openapis.org/oas/v3.1.0
• JSON Schema: https://json-schema.org/understanding-json-schema/index.html and https://json-schema.org/draft/2020-12/json-schema-core.html
• The list of most popular alternatives: https://tools.openapis.org

License

MIT licensed. See the bundled LICENSE file for more details.

openapi's Issues

TODO: validate examples

find a way to validate the examples in given spec

replacing validate package with in place ValidateSpec function

Does anyone use the validate package? I'm thinking about replacing it with in-place solution, like <T>.ValidateSpec(opts) function.

pros: no external dependencies, more flexible, like the validation of references or examples
cons: the go code should be changed in case of changed official specification

Thank you!

Just wanted to tell you, that this lib is a life safer for me!
Thank you!

I can finally implement an OpenAPI 3.1.0 spec in swaggo.
Already started it, it's working perfectly fine so far.

If i find anything missing, i'll open a PR :)