openapiparser

package module
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 3, 2021 License: MIT Imports: 14 Imported by: 0

README

OpenAPI Parser

Disclaimer: Work in progress.

Sounds good, but this is not probably what you are looking for, this library parses only the openapi spec files that I write, not the full specification. sorry not sorry

How to use

spec, err := openapi.Parse("api/spec")
Spec

The spec object contains everything this information from the spec

  • info metadata
  • paths
  • schemas
  • responses
  • parameters

Limitations

Only YAML

It does only parse file in YAML format.

Composition and inheritance.

Both are not supported, so these keys in schemas will trigger errors

  • discriminator
  • allOf
  • oneOf
  • anyOf
  • not
Circular dependencies

Circular dependencies between schema files will trigger an error

Path definitions

It only supports file references, not inlined path definitions

Supported

paths:
  /foo:
    $ref: "paths/foo.yml"

Unsupported

paths:
  /foo:
    get:
      summary: Get Foo
      # ... continues path definition
Parameters definitions,

Does not support path references in the root spec file.

Supported

components:
  parameters:
    Foo:
      in: query
      type: string
      # ... continues parameter

Unsupported

components:
  parameters:
    Foo:
      $ref: "parameters/foo.yml"
Local schemas

Does not support local definitions for other files other than the root spec file

For example, given this definition in the root file openapi.yml

components:
  schemas:
    Foo:
      $ref: "schemas/foo.yml"

Supported

$ref: "../path/openapi.yml#/components/schemas/Foo"

Unsupported

$ref: "../path/anotherfile.yml#/components/schemas/Foo"
Additional Properties.

The parser will trigger an error is key additionalProperties is defined.

Response headers references

Does not support reference is response headers.

Caveats

Example and default

Does not parse default or example keys in the object schema, bot remain "as is" in a string value.

Examples:

default: foo => "foo"
default: 1 => "1"

With this example

example:
 foo: bar
 num: 1

You'll get it as a string, including newline characters:

foo: var
num: 1

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Callback added in v0.9.3

type Callback struct {
	Name      string     `yaml:"name"`
	URL       string     `yaml:"url"`
	Endpoints []Endpoint `yaml:"endpoints"`
}

type Contact

type Contact struct {
	Name  string `yaml:"name,omitempty"`
	URL   string `yaml:"url,omitempty"`
	Email string `yaml:"email,omitempty"`
}

type ContentTypes

type ContentTypes map[string]MediaType

type Endpoint

type Endpoint struct {
	Method      string      `yaml:"method,omitempty"`
	Summary     string      `yaml:"summary,omitempty"`
	Description string      `yaml:"description,omitempty"`
	Tags        []string    `yaml:"tags,omitempty"`
	OperationID string      `yaml:"operationId,omitempty"`
	Parameters  []Parameter `yaml:"parameters,omitempty"`
	RequestBody RequestBody `yaml:"requestBody,omitempty"`
	Responses   []Response  `yaml:"responses,omitempty"`
	Callbacks   []Callback  `yaml:"callbacks,omitempty"`
}

type EnumOptionX

type EnumOptionX struct {
	Key         string `yaml:"title,omitempty"`
	Description string `yaml:"description,omitempty"`
}

type EnumX

type EnumX struct {
	Options []EnumOptionX
}
type Header struct {
	Schema      Schema `yaml:"schema,omitempty"`
	Description string `yaml:"description,omitempty"`
	Example     string `yaml:"example,omitempty"`
}

type Headers added in v0.10.0

type Headers map[string]Header

type Info

type Info struct {
	Title          string  `yaml:"title,omitempty"`
	Description    string  `yaml:"description,omitempty"`
	TermsOfService string  `yaml:"termsOfService,omitempty"`
	Contact        Contact `yaml:"contact"`
	License        License `yaml:"license,omitempty"`
	Version        string  `yaml:"version,omitempty"`
}

type License

type License struct {
	Name string `yaml:"name,omitempty"`
	URL  string `yaml:"url,omitempty"`
}

type MediaType

type MediaType struct {
	Schema   Schema `yaml:"schema,omitempty"`
	Example  string `yaml:"example,omitempty"`
	Examples string `yaml:"examples,omitempty"`
}

type Parameter

type Parameter struct {
	Ref         string `yaml:"$ref,omitempty"`
	In          string `yaml:"in,omitempty"`
	Name        string `yaml:"name,omitempty"`
	Required    bool   `yaml:"required,omitempty"`
	Description string `yaml:"description,omitempty"`
	Schema      Schema `yaml:"schema,omitempty"`
}

type Path

type Path struct {
	Key       string     `yaml:"key,omitempty"`
	Ref       string     `yaml:"$ref,omitempty"`
	Endpoints []Endpoint `yaml:"endpoints"`
}

type RequestBody

type RequestBody struct {
	Required     bool         `yaml:"required,omitempty"`
	Description  string       `yaml:"description,omitempty"`
	ContentTypes ContentTypes `yaml:"content,omitempty"`
	Example      string       `yaml:"example,omitempty"`
}

type Response

type Response struct {
	Ref          string       `yaml:"$ref,omitempty"`
	Status       string       `yaml:"status,omitempty"`
	Description  string       `yaml:"description,omitempty"`
	ContentTypes ContentTypes `yaml:"content,omitempty"`
	Headers      Headers      `yaml:"headers,omitempty"`
}

type Schema

type Schema struct {
	// Key is dependent on where the schema was found. It may represent the name
	// of the Schema if it's the root spec components map, but it's
	// the key of the property is it was found as a nested schema.
	Key string `yaml:"key,omitempty"`
	// Name is the name of the schema if it's present in the
	// components schemas section
	Name string `yaml:"name,omitempty"`

	Ref              string   `yaml:"$ref,omitempty"`
	Type             string   `yaml:"type,omitempty"`
	Description      string   `yaml:"description,omitempty"`
	Title            string   `yaml:"title,omitempty"`
	Required         []string `yaml:"required,omitempty"`
	Nullable         bool     `yaml:"Nullable,omitempty"`
	Format           string   `yaml:"format,omitempty"`
	Pattern          string   `yaml:"pattern,omitempty"`
	ReadOnly         bool     `yaml:"readOnly,omitempty"`
	WriteOnly        bool     `yaml:"writeOnly,omitempty"`
	Minimum          float64  `yaml:"minimum,omitempty"`
	Maximum          float64  `yaml:"maximum,omitempty"`
	ExclusiveMinimum float64  `yaml:"exclusiveMinimum,omitempty"`
	ExclusiveMaximum float64  `yaml:"exclusiveMaximum,omitempty"`
	MinItems         int      `yaml:"minItems,omitempty"`
	MaxItems         int      `yaml:"maxItems,omitempty"`
	UniqueItems      bool     `yaml:"uniqueItems,omitempty"`
	MinLength        int      `yaml:"minLength,omitempty"`
	MaxLength        int      `yaml:"maxLength,omitempty"`
	MinProperties    int      `yaml:"minProperties,omitempty"`
	MaxProperties    int      `yaml:"maxProperties,omitempty"`
	Enum             []string `yaml:"enum,omitempty"`
	EnumX            EnumX    `yaml:"x-enum,omitempty"`
	Example          string   `yaml:"example,omitempty"`
	Default          string   `yaml:"default,omitempty"`
	Properties       []Schema `yaml:"properties,omitempty"`
	Items            *Schema  `yaml:"items,omitempty"`
}

func (Schema) JSON

func (s Schema) JSON(op SchemaOp) (string, error)

func (Schema) JSONIndent

func (s Schema) JSONIndent(op SchemaOp, indent string) (string, error)

type SchemaOp

type SchemaOp int
const (
	ReadOp SchemaOp = iota << 1
	WriteOp
)

type Server

type Server struct {
	URL         string `yaml:"url,omitempty"`
	Description string `yaml:"description,omitempty"`
}

type Spec

type Spec struct {
	OpenAPI    string      `yaml:"openapi,omitempty"`
	Info       Info        `yaml:"info,omitempty"`
	Servers    []Server    `yaml:"servers,omitempty"`
	Paths      []Path      `yaml:"paths,omitempty"`
	Schemas    []Schema    `yaml:"schemas,omitempty"`
	Parameters []Parameter `yaml:"parameters,omitempty"`
}

func Parse

func Parse(file string) (spec *Spec, err error)

Directories

Path Synopsis
cmd
cli

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL