loads

package module
v0.22.0 Latest Latest
Warning

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

Go to latest
Published: Mar 9, 2024 License: Apache-2.0 Imports: 9 Imported by: 3,105

README

Loads OAI specs Build Status codecov

license GoDoc Go Report Card

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

Examples

Constants

This section is empty.

Variables

This section is empty.

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 added in v0.20.0

type DocLoaderWithMatch struct {
	Fn    DocLoader
	Match DocMatcher
}

DocLoaderWithMatch describes a loading function for a given extension match.

func NewDocLoaderWithMatch added in v0.20.0

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 added in v0.20.0

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 added in v0.20.0

func WithDocLoader(l DocLoader) LoaderOption

WithDocLoader sets a custom loader for loading specs

func WithDocLoaderMatches added in v0.20.0

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.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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