Documentation
¶
Overview ¶
Package route holds spec descriptors shared by the OpenAPI and AsyncAPI renderers: HTTP operation shapes and the security-scheme vocabulary.
A Route is a transport-agnostic descriptor for a single HTTP operation: method, path, parameters, request body, and responses. Codecs supply the schemas; renderers (such as render/openapi) consume routes to emit specs. Route/Param/Body/Response are HTTP-only and used solely by api/rest and render/openapi.
SecurityScheme, SecurityRequirement, and OAuthFlows are transport-agnostic: the same bearer/apiKey/oauth2/openIdConnect vocabulary applies to both OpenAPI (REST, via api/rest) and AsyncAPI (pub/sub channels, via api/events) security schemes, so it lives here rather than being duplicated per renderer. See render/openapi and render/asyncapi/v3 for the consumers.
Typical usage:
routes := []route.Route{
{
Method: "POST",
Path: "/users",
OperationID: "createUser",
Summary: "Create a user",
RequestBody: &route.Body{
Required: true,
Schema: CreateUserCodec.Schema,
SchemaName: "CreateUserRequest",
},
Responses: []route.Response{
{Status: "201", Description: "Created", Schema: &UserCodec.Schema, SchemaName: "User"},
},
},
}
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Body ¶
type Body struct {
Description string
Required bool
// Schema is the payload schema. Required when SchemaName is non-empty.
Schema schema.Schema
// SchemaName, when non-empty, emits a $ref and registers Schema in components/schemas.
SchemaName string
// ContentType is the primary media type for the request body. Defaults to
// "application/json". Ignored when ContentTypes is non-empty.
ContentType string
// ContentTypes, when non-empty, lists all media types this body can accept.
// The renderer emits the schema under every listed content type in the spec.
// Takes precedence over ContentType when set.
ContentTypes []string
}
Body describes an HTTP request body.
When SchemaName is non-empty, the renderer emits a $ref to components/schemas and registers Schema under that name automatically. When SchemaName is empty, Schema is inlined in the operation.
type OAuthFlow ¶ added in v0.8.0
type OAuthFlow struct {
// AuthorizationURL is required for implicit and authorizationCode flows.
AuthorizationURL string
// TokenURL is required for password, clientCredentials, and authorizationCode flows.
TokenURL string
RefreshURL string // optional
Scopes map[string]string // scope name → description
}
OAuthFlow describes a single OAuth 2.0 flow.
type OAuthFlows ¶ added in v0.8.0
type OAuthFlows struct {
Implicit *OAuthFlow
Password *OAuthFlow
ClientCredentials *OAuthFlow
AuthorizationCode *OAuthFlow
}
OAuthFlows holds the OAuth 2.0 flow definitions for an oauth2 security scheme. Set only the flows that apply to the scheme.
type Response ¶
type Response struct {
Status string // "200", "201", "default", "2XX", etc.
Description string
// Schema is the response body schema. Nil means no response body.
Schema *schema.Schema
// SchemaName, when non-empty, emits a $ref and registers Schema in components/schemas.
SchemaName string
ContentType string // defaults to "application/json"; ignored when ContentTypes is non-empty
// ContentTypes, when non-empty, lists all content types this response can produce.
// The renderer emits the schema under every listed content type in the spec.
// Takes precedence over ContentType when set.
ContentTypes []string
// Headers describes response headers emitted by this operation.
Headers []Param
}
Response describes one HTTP response for an operation.
Status is the HTTP status code as a string: "200", "201", "default", "2XX", etc. When SchemaName is non-empty, the renderer emits a $ref to components/schemas. A nil Schema with empty SchemaName produces a description-only response (e.g. 204).
type Route ¶
type Route struct {
Method string // GET, POST, PUT, PATCH, DELETE
Path string // e.g. /users/{id}
OperationID string
Summary string
Description string
Tags []string
PathParams []Param
QueryParams []Param
CookieParams []Param
HeaderParams []Param
RequestBody *Body
Responses []Response
// Security, when non-nil, overrides global security for this operation.
// An empty slice explicitly declares "no auth required" for the operation.
// nil means "inherit global security".
Security []SecurityRequirement
}
Route describes a single HTTP operation.
type SecurityRequirement ¶ added in v0.8.0
SecurityRequirement maps a scheme name to the required OAuth 2.0 scopes. For non-OAuth schemes the scopes slice is empty.
nil Security on a Route means "inherit global security". An empty []SecurityRequirement means "no auth required" for that operation.
func Require ¶ added in v0.8.0
func Require(scheme string, scopes ...string) SecurityRequirement
Require returns a SecurityRequirement for the named scheme with optional OAuth 2.0 scopes. For non-OAuth schemes pass no scopes.
route.Require("bearerAuth") // bearer — no scope restriction
route.Require("oauth2", "read:users", "admin") // oauth2 with required scopes
type SecurityScheme ¶ added in v0.8.0
type SecurityScheme struct {
Type SecuritySchemeType
Description string
// Name is the header / query / cookie key name for apiKey schemes.
Name string
// In is the location for apiKey schemes: "header", "query", or "cookie".
In string
// Scheme is the HTTP authentication scheme: "bearer", "basic", "digest".
Scheme string
// BearerFormat is informational (e.g. "JWT") and only relevant for bearer schemes.
BearerFormat string
// Flows defines the OAuth 2.0 flows; required for oauth2 schemes.
Flows *OAuthFlows
// OpenIDConnectURL is the well-known discovery URL for openIdConnect schemes.
OpenIDConnectURL string
}
SecurityScheme is a spec-only descriptor for an OpenAPI / AsyncAPI security scheme. It carries no runtime codec; higher-level packages (api/rest, api/events) embed SecurityScheme and add a Codec field for credential extraction and format validation.
Use the named constructor helpers (BearerScheme, APIKeyScheme, etc.) rather than constructing SecurityScheme literals directly.
func APIKeyScheme ¶ added in v0.8.0
func APIKeyScheme(name, in string) SecurityScheme
APIKeyScheme returns an API key SecurityScheme. name is the header / query / cookie key. in is "header", "query", or "cookie".
func BasicScheme ¶ added in v0.8.0
func BasicScheme() SecurityScheme
BasicScheme returns an HTTP basic authentication SecurityScheme.
func BearerScheme ¶ added in v0.8.0
func BearerScheme(bearerFormat string) SecurityScheme
BearerScheme returns an HTTP bearer token SecurityScheme. bearerFormat is informational (e.g. "JWT"); pass an empty string to omit it.
func OAuth2Scheme ¶ added in v0.8.0
func OAuth2Scheme(flows OAuthFlows) SecurityScheme
OAuth2Scheme returns an OAuth 2.0 SecurityScheme with the given flows.
func OpenIDConnectScheme ¶ added in v0.8.0
func OpenIDConnectScheme(url string) SecurityScheme
OpenIDConnectScheme returns an OpenID Connect SecurityScheme. url is the well-known OpenID Connect discovery URL.
type SecuritySchemeType ¶ added in v0.8.0
type SecuritySchemeType string
SecuritySchemeType identifies the type of an OpenAPI / AsyncAPI security scheme.
const ( SecuritySchemeAPIKey SecuritySchemeType = "apiKey" SecuritySchemeHTTP SecuritySchemeType = "http" SecuritySchemeOAuth2 SecuritySchemeType = "oauth2" SecuritySchemeOpenIDConnect SecuritySchemeType = "openIdConnect" )
Source Files