openapi

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Nov 12, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package openapi turns an OpenAPI 3.0 or 3.1 description, in JSON or YAML, into a candidate policy document and a report of what it mapped, assumed, changed and refused. It runs offline: it reads only the files it is named, never fetches a reference, and never activates anything; the result is staged and trialled like any other draft.

The description is untrusted input. It is size- and depth-bounded before mapping, YAML constructs JSON cannot express are refused, and every operation is checked by the real compiler before it is accepted, so the import never holds a second copy of the compiler's rules. It imports only policy and compile.

Index

Constants

View Source 
const (
	ExitComplete = 0 // everything mapped
	ExitFailed   = 1 // nothing written
	ExitPartial  = 2 // written, but some operations were refused or widened
)

Exit statuses of the import command.

View Source 
const (
	CodeMethod          = "METHOD_REFUSED"
	CodeOperationID     = "OPERATION_ID_INVALID"
	CodeDuplicateID     = "OPERATION_ID_DUPLICATE"
	CodePathTemplate    = "PATH_TEMPLATE_UNSUPPORTED"
	CodeTargetCollision = "TARGET_COLLISION"
	CodeSecurity        = "SECURITY_SCHEME_UNSUPPORTED"
	CodeMediaType       = "MEDIA_TYPE_UNSUPPORTED"
	CodeCycle           = "SCHEMA_CYCLE"
	CodeExternalRef     = "EXTERNAL_REF"
	CodeRefInvalid      = "REF_INVALID"
	CodeKeyword         = "SCHEMA_KEYWORD_UNSUPPORTED"
	CodeSchemaLimit     = "SCHEMA_LIMIT_EXCEEDED"
	CodeCompiler        = "COMPILER_REFUSED"
)

Refusal codes for one operation.

View Source 
const CodeExtension = "EXTENSION_INVALID"

CodeExtension refuses an operation whose x-apiward-* member is unknown or invalid.

View Source 
const DefaultBodyBytes = 16384

DefaultBodyBytes is the body limit given to imported operations unless the caller sets one; it is reported as assumed.

View Source 
const MaxSpecBytes = 1 << 20

MaxSpecBytes is the largest description accepted, checked before parsing.

View Source 
const NoteDefaultSignIn = "no security stated; sign-in required by default"

NoteDefaultSignIn notes an operation whose description states no security: the import requires sign-in, which is stricter than the description.

Variables

This section is empty.

Functions

func Command 

func Command(args []string, stderr io.Writer) int

Command runs "policy <subcommand>" and returns the exit status. It reads only the files named by flags and creates only the out and report files; an unknown subcommand, or a bad command line, prints the usage.

Types

type Assumed 

type Assumed struct {
	Operation string `json:"operation"`
	Field     string `json:"field"`
	Value     any    `json:"value"`
	Note      string `json:"note,omitempty"`
}

Assumed is a value the description does not state and the import chose.

type Changed 

type Changed struct {
	Operation string `json:"operation"`
	Field     string `json:"field"`
	Note      string `json:"note"`
}

Changed is behaviour the gateway enforces differently from the description.

type ExportOptions 

type ExportOptions struct {
	API          string // the API to describe
	WithUpstream bool   // write the upstream address as a server
}

ExportOptions are the administrator's choices for one export.

type ExportReport 

type ExportReport struct {
	API        string     `json:"api"`
	Operations int        `json:"operations"`
	Exported   []Exported `json:"exported"`
	Changed    []Changed  `json:"changed"`
	Omitted    []string   `json:"omitted"`
}

ExportReport is the stable account of one export. Every list is present.

func Export 

func Export(p policy.Policy, options ExportOptions) (map[string]any, *ExportReport, error)

Export describes one API of a policy the compiler accepts. It returns the description as JSON-ready values and the report, or an error, in which case nothing may be written. It has no side effects.

func (*ExportReport) Exit 

func (r *ExportReport) Exit() int

Exit is partial when the description means something different from the policy anywhere, so a script cannot miss it.

type Exported 

type Exported struct {
	Operation string `json:"operation"`
	Method    string `json:"method"`
	Path      string `json:"path"`
}

Exported is one operation written to the description.

type Format 

type Format string

Format is the syntax a description is written in. 

const (
	JSON Format = "json"
	YAML Format = "yaml"
)

type Mapped 

type Mapped struct {
	Method    string `json:"method"`
	Path      string `json:"path"`
	Operation string `json:"operation"`
	Target    string `json:"target"`
	Auth      string `json:"auth"`
	Note      string `json:"note,omitempty"`
}

Mapped is an imported operation; Note explains a default it relies on.

type NotEnforced 

type NotEnforced struct {
	Operation string `json:"operation"`
	Parameter string `json:"parameter"`
	In        string `json:"in"`
}

NotEnforced is a parameter the gateway does not validate.

type Options 

type Options struct {
	API          string        // the API to create or replace
	Upstream     string        // an upstream of Base that serves the API
	Base         policy.Policy // the policy the result is built on
	MaxBodyBytes int64         // body limit of body rules without x-apiward-max-bytes
	WithPermits  bool          // read x-apiward-roles into permits
}

Options are the administrator's choices for one import.

type Permit 

type Permit struct {
	Role      string `json:"role"`
	Operation string `json:"operation"`
}

Permit is a base permit removed because its operation was replaced.

type Refused 

type Refused struct {
	Method     string `json:"method"`
	Path       string `json:"path"`
	Code       string `json:"code"`
	Message    string `json:"message"`
	Field      string `json:"field,omitempty"`
	Suggestion string `json:"suggestion,omitempty"`
}

Refused is an operation left out of the output, with the reason.

type Removed 

type Removed struct {
	Operation string `json:"operation"`
	Field     string `json:"field"`
}

Removed names a schema annotation dropped from an operation.

type Report 

type Report struct {
	SpecVersion        string        `json:"spec_version"`
	SourceFormat       Format        `json:"source_format"`
	API                string        `json:"api"`
	OperationsInSpec   int           `json:"operations_in_spec"`
	Mapped             []Mapped      `json:"mapped"`
	Widened            []Mapped      `json:"widened"`
	Assumed            []Assumed     `json:"assumed"`
	Changed            []Changed     `json:"changed"`
	Refused            []Refused     `json:"refused"`
	NeedsPermissions   []string      `json:"needs_permissions"`
	ScopesNotMapped    []string      `json:"scopes_not_mapped"`
	NotEnforced        []NotEnforced `json:"not_enforced"`
	AnnotationsRemoved []Removed     `json:"annotations_removed"`
	RemovedOperations  []string      `json:"removed_operations"`
	RemovedPermits     []Permit      `json:"removed_permits"`
	Ignored            []string      `json:"ignored"`
}

Report is the stable, documented account of one import. Every list is present, never null, and in a deterministic order.

func Import 

func Import(spec []byte, format Format, options Options) (policy.Policy, *Report, error)

Import maps a description onto the base policy. It returns the result, which the real decoder and compiler have accepted, and the report; or an error, in which case nothing may be written. It has no side effects.

func (*Report) Exit 

func (r *Report) Exit() int

Exit is the command's status for a written result: partial when any operation was refused or widened, so a script cannot miss either.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.