openapiparser

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

• type Callback
• type Contact
• type ContentTypes
• type Endpoint
• type EnumOptionX
• type EnumX
• type Info
• type License
• type MediaType
• type Parameter
• type Path
• type RequestBody
• type Response
• type Schema
  • func (s Schema) JSON(op SchemaOp) (string, error)
  • func (s Schema) JSONIndent(op SchemaOp, indent string) (string, error)
• type SchemaOp
• type Server
• type Spec
  • func Parse(file string) (spec *Spec, err error)

Types

type Callback

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 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"`
}

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)