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 ¶
const ResponseDirective = "//avero:response"
ResponseDirective states the answer of a handler.
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 ¶
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 ¶
MarshalJSON writes the document with its paths in order. See AN-4.
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 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.