loads

README

Loads OAI specs

Loading of OAI specification documents from local or remote locations. Supports JSON and YAML documents.

Documentation

Overview

Package loads provides document loading methods for swagger (OAI) specifications.

It is used by other go-openapi packages to load and run analysis on local or remote spec documents.

Index

• func AddLoader(predicate DocMatcher, load DocLoader)
• func JSONDoc(path string) (json.RawMessage, error)
• type DocLoader
• type DocLoaderWithMatch
  • func NewDocLoaderWithMatch(fn DocLoader, matcher DocMatcher) DocLoaderWithMatch
• type DocMatcher
• type Document
  • func Analyzed(data json.RawMessage, version string, options ...LoaderOption) (*Document, error)
  • func Embedded(orig, flat json.RawMessage, options ...LoaderOption) (*Document, error)
  • func JSONSpec(path string, options ...LoaderOption) (*Document, error)
  • func Spec(path string, options ...LoaderOption) (*Document, error)
  • func (d *Document) BasePath() string
  • func (d *Document) Expanded(options ...*spec.ExpandOptions) (*Document, error)
  • func (d *Document) Host() string
  • func (d *Document) OrigSpec() *spec.Swagger
  • func (d *Document) Pristine() *Document
  • func (d *Document) Raw() json.RawMessage
  • func (d *Document) ResetDefinitions() *Document
  • func (d *Document) Schema() *spec.Schema
  • func (d *Document) Spec() *spec.Swagger
  • func (d *Document) SpecFilePath() string
  • func (d *Document) Version() string
• type LoaderOption
  • func WithDocLoader(l DocLoader) LoaderOption
  • func WithDocLoaderMatches(l ...DocLoaderWithMatch) LoaderOption

Examples

• LoaderOption
• Spec

Functions

func AddLoader

func AddLoader(predicate DocMatcher, load DocLoader)

AddLoader for a document, executed before other previously set loaders.

This sets the configuration at the package level.

NOTE:

• this updates the default loader used by github.com/go-openapi/spec
• since this sets package level globals, you shouln't call this concurrently

func JSONDoc

func JSONDoc(path string) (json.RawMessage, error)

JSONDoc loads a json document from either a file or a remote url

Types

type DocLoader

type DocLoader func(string) (json.RawMessage, error)

DocLoader represents a doc loader type

type DocLoaderWithMatch

type DocLoaderWithMatch struct {
	Fn    DocLoader
	Match DocMatcher
}

DocLoaderWithMatch describes a loading function for a given extension match.

func NewDocLoaderWithMatch

func NewDocLoaderWithMatch(fn DocLoader, matcher DocMatcher) DocLoaderWithMatch

NewDocLoaderWithMatch builds a DocLoaderWithMatch to be used in load options

type DocMatcher

type DocMatcher func(string) bool

DocMatcher represents a predicate to check if a loader matches

type Document

type Document struct {
	// specAnalyzer
	Analyzer *analysis.Spec
	// contains filtered or unexported fields
}

Document represents a swagger spec document

func Analyzed

func Analyzed(data json.RawMessage, version string, options ...LoaderOption) (*Document, error)

Analyzed creates a new analyzed spec document for a root json.RawMessage.

func Embedded

func Embedded(orig, flat json.RawMessage, options ...LoaderOption) (*Document, error)

Embedded returns a Document based on embedded specs. No analysis is required

func JSONSpec

func JSONSpec(path string, options ...LoaderOption) (*Document, error)

JSONSpec loads a spec from a json document

func Spec

func Spec(path string, options ...LoaderOption) (*Document, error)

Spec loads a new spec document from a local or remote path

Example

package main

import (
	"fmt"

	"github.com/go-openapi/loads"
)

func main() {
	// Example with default loaders defined at the package level

	path := "fixtures/yaml/swagger/spec.yml"
	doc, err := loads.Spec(path)
	if err != nil {
		fmt.Println("Could not load this spec")
		return
	}

	fmt.Printf("Spec loaded: %q\n", doc.Host())

}

Output:

Spec loaded: "api.example.com"

func (*Document) BasePath

func (d *Document) BasePath() string

BasePath the base path for the API specified by this spec

func (*Document) Expanded

func (d *Document) Expanded(options ...*spec.ExpandOptions) (*Document, error)

Expanded expands the $ref fields in the spec document and returns a new spec document

func (*Document) Host

func (d *Document) Host() string

Host returns the host for the API

func (*Document) OrigSpec

func (d *Document) OrigSpec() *spec.Swagger

OrigSpec yields the original spec

func (*Document) Pristine

func (d *Document) Pristine() *Document

Pristine creates a new pristine document instance based on the input data

func (*Document) Raw

func (d *Document) Raw() json.RawMessage

Raw returns the raw swagger spec as json bytes

func (*Document) ResetDefinitions

func (d *Document) ResetDefinitions() *Document

ResetDefinitions gives a shallow copy with the models reset to the original spec

func (*Document) Schema

func (d *Document) Schema() *spec.Schema

Schema returns the swagger 2.0 schema

func (*Document) Spec

func (d *Document) Spec() *spec.Swagger

Spec returns the swagger spec object model

func (*Document) SpecFilePath

func (d *Document) SpecFilePath() string

SpecFilePath returns the file path of the spec if one is defined

func (*Document) Version

func (d *Document) Version() string

Version returns the version of this spec

type LoaderOption

type LoaderOption func(*options)

LoaderOption allows to fine-tune the spec loader behavior

Example

package main

import (
	"encoding/json"
	"fmt"
	"os"
	"path/filepath"

	"github.com/go-openapi/loads"
	"github.com/go-openapi/swag"
)

func main() {
	// Example with custom loaders passed as options

	path := "fixtures/yaml/swagger/spec.yml"

	// a simpler version of loads.JSONDoc
	jsonLoader := loads.NewDocLoaderWithMatch(
		func(pth string) (json.RawMessage, error) {
			buf, err := os.ReadFile(pth)
			return json.RawMessage(buf), err
		},
		func(pth string) bool {
			return filepath.Ext(pth) == ".json"
		},
	)

	// equivalent to the default loader at the package level, which does:
	//
	//   loads.AddLoader(swag.YAMLMatcher, swag.YAMLDoc)
	yamlLoader := loads.NewDocLoaderWithMatch(
		swag.YAMLDoc,
		func(pth string) bool {
			return filepath.Ext(pth) == ".yml"
		},
	)

	doc, err := loads.Spec(path, loads.WithDocLoaderMatches(jsonLoader, yamlLoader))
	if err != nil {
		fmt.Println("Could not load this spec")
		return
	}

	fmt.Printf("Spec loaded: %q\n", doc.Host())

}

Output:

Spec loaded: "api.example.com"

func WithDocLoader

func WithDocLoader(l DocLoader) LoaderOption

WithDocLoader sets a custom loader for loading specs

func WithDocLoaderMatches

func WithDocLoaderMatches(l ...DocLoaderWithMatch) LoaderOption

WithDocLoaderMatches sets a chain of custom loaders for loading specs for different extension matches.

Loaders are executed in the order of provided DocLoaderWithMatch'es.