chanced / openapi Goto Github PK

an OpenAPI 3.x library for go

License: MIT License

Go 100.00%

golang go openapi openapi3-1 openapi-spec openapi-validation openapi3

openapi's Introduction

openapi - An OpenAPI 3.x library for go

openapi is a library for parsing and validating OpenAPI 3.1, 3.0. The intent of the library is to offer building blocks for code and documentation generation.

⚠️ This library is under active development; there may be breaking changes and bugs.

Features

$ref resolution
All keys retain their order from the markup using slices of key/values which aids in code generation.
Validation (see the validation section)
All non-primitive nodes have an absolute & relative location
Strings are text.Text which has case conversions and strings functions as methods.
Extensions, unknown JSON Schema keywords, examples, and a few other fields are instances of jsonx.RawMessage which comes with a few helper methods.
Supports both JSON and YAML

Usage

package main

import (
    "github.com/chanced/openapi"
    "github.com/chanced/uri"
    "github.com/santhosh-tekuri/jsonschema/v5"
    "embed"
    "io"
    "path/filepath"
    "log"
)

//go:embed spec
var specFiles embed.FS

func main() {
    ctx := context.Background()

    c, err := openapi.SetupCompiler(jsonschema.NewCompiler()) // adding schema files
    if err != nil {
        log.Fatal(err)
    }
    v, err := openapi.NewValidator(c)
    if err != nil {
        log.Fatal(err)
    }

    fn := func(_ context.Context, uri uri.URI, kind openapi.Kind) (openapi.Kind, []byte, error){
        f, err := specFiles.Open(fp)
        if err != nil {
            log.Fatal(err)
        }
        // you can return either JSON or YAML
        d, err := io.ReadAll(f)
        if err != nil{
            log.fatal(err)
        }
        // use the uri or the data to determine the Kind
        return openapi.KindDocument, d, nil
    }
    // you can Load either JSON or YAML
    // Load validates the Document as well.
    doc, err := openapi.Load(ctx, "spec/openapi.yaml", v, fn)
    if err != nil{
        log.Fatal(err)
    }
    _ = doc // *openapi.Document
}

Validation

The standard validator (StdValidator) currently validates OpenAPI documents with JSON Schema. Per OpenAPI's documentation, this may not be enough to properly encapsulate all the nuances of a specification. However, JSON Schema is able to successfully validate the current OpenAPI 3.1 Specification test suite.

Validation is an area that still needs work. If you do find cases where the current validator is not sufficient, please open an issue so that the library can be updated with proper coverage of that case.

Dependencies

Dependency	Usage
github.com/santhosh-tekuri/jsonschema/v5	used in the `StdValidator` to validate OpenAPI documents & components
github.com/chanced/caps/text	used for all string fields to provide case conversion and functions from `strings` as methods
github.com/chanced/jsonpointer	relative locations of all non-scalar nodes
github.com/tidwall/gjson	JSON parsing
github.com/chanced/jsonx	raw JSON type and a toolkit for json type detection & parsing
github.com/chanced/maps	small utility used to sort `Extensions`
github.com/chanced/transcode	used to transform YAML into JSON and vice versa
github.com/chanced/uri	used to represent URIs
github.com/Masterminds/semver	openapi field and version detection of OpenAPI documents
gopkg.in/yaml.v3	needed to satisfy `yaml.Marshaler` and `yaml.Unmarshaler`
github.com/google/go-cmp	testing purposes

Contributions

Please feel free to open up an issue or create a pull request if you find issues or if there are features you'd like to see added.

License

MIT

openapi's People

Contributors

Stargazers

Watchers

Forkers

up9inc jarrodhroberson

openapi's Issues

If the reference is pointing to a root document, the expected Kind is not provided

Schema validation with the StdValidator is erroring out

UnmarshalYAML is not working properly. It does not impact `Load` though.

`$dynamicRef` / `$dynamicAnchor` resolution

Currently $dynamicRef does not override with the dynamic resolution. There are three issues at play:

When loading a document, all nodes are parsed once and referenced when later encountered in $ref, $dynamicRef, $recursiveRef. This is fine for $ref except when the referenced schema has a $dynamicRef or $recursiveRef. In which case, those references need to be replaced with the schema containing the $dynamicAnchor. Currently, if the schema containing $dynamicRef were updated to the reflect the new $dynamicAnchor then it would happen across the application.
$dynamicRefs are designed to be evaluated at runtime against data to ensure validity. This means that $dynamicAnchors can reside in conditional branches, such as if/then/else. Without data to compare against, there is no way of knowing which anchor to select.
$dynamicRefs are transitive. This means that in a situation where:

FileA has a $ref to FileB and the $dynamicAnchor T
FileB has a $ref to FileC
FileC has a $dynamicRef #T

In order to solve dynamic overlay, after the document is loaded and resolved, every schema is going to need to be cloned and reassigned. Use a map of AbsoluteLocation of the SchemaRef to ensure that a reference hasn't been visited in the cloning process.

I have no idea how to solve conditional/dynamic resolution.

The solution to the third depends on how the second is solved.

Duplicate anchors should not return an error

If there are duplicate named anchors within the same file, an error is returned. This is not up to spec.

It was added to try and allow $dynamicRef but those are transitive anyway so it doesn't matter.

Examples and Example in ParameterObj

Hello,

Thanks for your nice library, it's a rare project that supports OAS 3.1

I have a question about examples fields in parameters. In OAS Spec I see that there can be 2 options to specify examples (https://spec.openapis.org/oas/v3.1.0#fixed-fields-9): example and examples, mutually exclusive.

In the ParameterObj I only see the Examples field. Trying to load the following document with library gives no access to example value:

{
  "openapi": "3.1.0",
  "info": {
    "title": "",
    "version": ""
  },
  "paths": {
    "/catalogue/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "schema": {
            "type": "string"
          },
          "example": "some-uuid-maybe"
        }
      ]
    }
  }
}

Is there a plan to support the example, as defined in OAS 3.1 specification?

Improve code coverage

Currently sitting at 44%.

jsonpointer `Resolve`, `Assign`, `Delete`

chanced/jsonpointer#3

Improve documentation

There are a lot of methods, types, and such that lack documentation.

Loading remote ref is causing panics

`$recursiveRef` / `$recursiveAnchor`

Same as #10 but the resolution is different.

Unable to load valid OAS

The following code fails with message Failed: json: cannot unmarshal object into Go struct field openapi.paths of type openapi.Example. The spec is quite simple and valid, as far as I can see...

func TestLoadData(t *testing.T) {
	data := `{
	  "openapi": "3.1.0",
	  "info": {
		"title": "",
		"version": "",
		"description": "Test file for loading pre-existing OAS"
	  },
	  "paths": {
		"/catalogue/{id}": {
		  "parameters": [
			{
			  "name": "id",
			  "in": "path",
			  "required": true,
			  "style": "simple",
			  "schema": {
				"type": "string"
			  },
			  "examples": {
				"an example": {
				  "value": "someval"
				}
			  }
			}
		  ]
		},
		"/catalogue/{id}/details": {
		  "parameters": [
			{
			  "name": "id",
			  "in": "path",
			  "style": "simple",
			  "required": true,
			  "schema": {
				"type": "string"
			  },
			  "example": "some-uuid-maybe"
			}
		  ]
		}
	  }
	}`

	var oas openapi.OpenAPI
	err := json.Unmarshal([]byte(data), &oas)
	if err != nil {
		t.Errorf("Failed: %s", err)
		t.FailNow()
	}
}

Schema examples question

Hi,
I'm trying to work with the "examples" property of the SchemaObj, and I found that the Examples property is of type RawMessage, although the JSONSchema spec declares that it can only be array (reading here https://json-schema.org/understanding-json-schema/reference/generic.html).

Am I interpreting it wrong, or should the Examples property be a sort of "array of RawMessage", to simplify the interface of working with it?

MarshalYAML is not producing proper results

All MarshalYAML methods are not producing proper results. MarshalYAML does not detect whether the result is a slice of bytes and so it is marshaling the bytes as an array.

This does not effect Load.