openapi

package
v0.2.3 Latest Latest
Warning

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

Go to latest
Published: Sep 9, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package openapi writes the OpenAPI description of an application, S14.

`avero routes --openapi` reads the routes of each module and the input type of each handler, and it writes an OpenAPI 3.1 document. It reads the source and runs nothing, so it needs no database and no running application.

The description carries what the code states: the path, the method, the parameters, the body and the validation of each field. It carries no answer schema, because a handler states its answer in Go and not in a tag. Write the answer of a route in the description of its module when a client needs it.

Index

Constants

View Source
const ResponseDirective = "//avero:response"

ResponseDirective states the answer of a handler.

View Source
const Version = "3.1.0"

Version is the version of the OpenAPI specification that the document follows.

Variables

This section is empty.

Functions

This section is empty.

Types

type Components

type Components struct {
	// Schemas maps the name of a type to its schema.
	Schemas map[string]Schema `json:"schemas"`
}

Components holds the schemas of the description.

type Document

type Document struct {
	// OpenAPI is the version of the specification.
	OpenAPI string `json:"openapi"`
	// Info states the name and the version of the application.
	Info Info `json:"info"`
	// Servers names the addresses of the application.
	Servers []Server `json:"servers,omitempty"`
	// Paths holds one item for each path, in path order. See AN-4.
	Paths map[string]PathItem `json:"paths"`
	// Components holds the schemas that the operations name.
	Components *Components `json:"components,omitempty"`
}

Document is one OpenAPI description.

func Generate

func Generate(opts Options) (*Document, error)

Generate reads the application and returns its description.

It finds each Routes method of a module, and it reads the input type of each handler that the routes name. The tags of the input type give the parameters, the body and the rules. See S5 and S14.

func (*Document) MarshalJSON

func (d *Document) MarshalJSON() ([]byte, error)

MarshalJSON writes the document with its paths in order. See AN-4.

func (*Document) Operation

func (d *Document) Operation(method, path string) (Operation, bool)

Operation returns one operation of the document.

func (*Document) PathNames

func (d *Document) PathNames() []string

PathNames returns the paths of the document, in order.

func (*Document) String

func (d *Document) String() string

String returns the document as JSON.

type Info

type Info struct {
	// Title is the name of the application.
	Title string `json:"title"`
	// Version is the version of the description.
	Version string `json:"version"`
	// Description states what the application does.
	Description string `json:"description,omitempty"`
}

Info states the name and the version of the application.

type MediaType

type MediaType struct {
	// Schema states the type of the body.
	Schema Schema `json:"schema"`
}

MediaType states the shape of one body.

type Operation

type Operation struct {
	// OperationID names the handler, such as posts.Create.
	OperationID string `json:"operationId"`
	// Summary is the first sentence of the comment of the handler.
	Summary string `json:"summary,omitempty"`
	// Tags names the module that owns the route.
	Tags []string `json:"tags,omitempty"`
	// Parameters holds the path parameters, the query parameters and the
	// headers.
	Parameters []Parameter `json:"parameters,omitempty"`
	// RequestBody states the body of the request.
	RequestBody *RequestBody `json:"requestBody,omitempty"`
	// Responses states the answers of the route.
	Responses map[string]Response `json:"responses"`
}

Operation is one route.

type Options

type Options struct {
	// Dir is the root of the application.
	Dir string
	// Title is the name of the application. An empty value takes the name of
	// the module.
	Title string
	// Version is the version of the description. An empty value is 0.1.0.
	Version string
	// Server is the address of the application. An empty value writes none.
	Server string
}

Options states one description.

type Parameter

type Parameter struct {
	// Name is the name that the request carries.
	Name string `json:"name"`
	// In is path, query or header.
	In string `json:"in"`
	// Required states a value that the route needs.
	Required bool `json:"required"`
	// Schema states the type and the rules of the value.
	Schema Schema `json:"schema"`
}

Parameter is one value that a route reads outside the body.

type PathItem

type PathItem map[string]Operation

PathItem holds the operations of one path.

type RequestBody

type RequestBody struct {
	// Required states a body that the route needs.
	Required bool `json:"required"`
	// Content holds one media type.
	Content map[string]MediaType `json:"content"`
}

RequestBody states the body of a request.

type Response

type Response struct {
	// Description states the answer in one line.
	Description string `json:"description"`
	// Content holds one media type. An answer with no body holds none.
	Content map[string]MediaType `json:"content,omitempty"`
}

Response is one answer of a route.

type Schema

type Schema struct {
	// Type is string, integer, number, boolean, array or object.
	Type string `json:"type,omitempty"`
	// Format states the shape of a string, such as email or uuid.
	Format string `json:"format,omitempty"`
	// MinLength and MaxLength bound a string.
	MinLength *int `json:"minLength,omitempty"`
	MaxLength *int `json:"maxLength,omitempty"`
	// Minimum and Maximum bound a number.
	Minimum *float64 `json:"minimum,omitempty"`
	Maximum *float64 `json:"maximum,omitempty"`
	// Enum lists the values that the rule oneof states.
	Enum []string `json:"enum,omitempty"`
	// Items states the member of an array.
	Items *Schema `json:"items,omitempty"`
	// Properties holds the members of an object.
	Properties map[string]Schema `json:"properties,omitempty"`
	// Required names the members that the object needs.
	Required []string `json:"required,omitempty"`
	// AdditionalProperties states an object that carries other members.
	AdditionalProperties *bool `json:"additionalProperties,omitempty"`
	// Ref names a schema of the components, such as
	// #/components/schemas/Task.
	Ref string `json:"$ref,omitempty"`
}

Schema is one JSON Schema node.

type Server

type Server struct {
	// URL is the address.
	URL string `json:"url"`
	// Description states what the address is.
	Description string `json:"description,omitempty"`
}

Server is one address of the application.

Jump to

Keyboard shortcuts

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