openapi

README

OpenAPI structures for Go

This library provides Go structures to marshal/unmarshal and reflect OpenAPI Schema documents.

For automated HTTP REST service framework built with this library please check github.com/swaggest/rest.

Features

• Type safe mapping of OpenAPI 3 documents with Go structures generated from schema.
• Type-based reflection of Go structures to OpenAPI 3.0 or 3.1 schema.
• Schema control with field tags
  • json for request bodies and responses in JSON
  • query, path for parameters in URL
  • header, cookie, formData, file for other parameters
  • form acts as query and formData
  • field tags named after JSON Schema/OpenAPI 3 Schema constraints
  • collectionFormat to unpack slices from string
    • csv comma-separated values,
    • ssv space-separated values,
    • pipes pipe-separated values (|),
    • multi ampersand-separated values (&),
    • json additionally to slices unpacks maps and structs,
• Flexible schema control with jsonschema-go

Example

Other examples.

reflector := openapi3.Reflector{}
reflector.Spec = &openapi3.Spec{Openapi: "3.0.3"}
reflector.Spec.Info.
    WithTitle("Things API").
    WithVersion("1.2.3").
    WithDescription("Put something here")

type req struct {
    ID     string `path:"id" example:"XXX-XXXXX"`
    Locale string `query:"locale" pattern:"^[a-z]{2}-[A-Z]{2}$"`
    Title  string `json:"string"`
    Amount uint   `json:"amount"`
    Items  []struct {
        Count uint   `json:"count"`
        Name  string `json:"name"`
    } `json:"items"`
}

type resp struct {
    ID     string `json:"id" example:"XXX-XXXXX"`
    Amount uint   `json:"amount"`
    Items  []struct {
        Count uint   `json:"count"`
        Name  string `json:"name"`
    } `json:"items"`
    UpdatedAt time.Time `json:"updated_at"`
}

putOp, err := reflector.NewOperationContext(http.MethodPut, "/things/{id}")
handleError(err)

putOp.AddReqStructure(new(req))
putOp.AddRespStructure(new(resp), func(cu *openapi.ContentUnit) { cu.HTTPStatus = http.StatusOK })
putOp.AddRespStructure(new([]resp), func(cu *openapi.ContentUnit) { cu.HTTPStatus = http.StatusConflict })

reflector.AddOperation(putOp)

getOp, err := reflector.NewOperationContext(http.MethodGet, "/things/{id}")
handleError(err)

getOp.AddReqStructure(new(req))
getOp.AddRespStructure(new(resp), func(cu *openapi.ContentUnit) { cu.HTTPStatus = http.StatusOK })

reflector.AddOperation(getOp)

schema, err := reflector.Spec.MarshalYAML()
if err != nil {
    log.Fatal(err)
}

fmt.Println(string(schema))

Output:

openapi: 3.0.3
info:
  description: Put something here
  title: Things API
  version: 1.2.3
paths:
  /things/{id}:
    get:
      parameters:
      - in: query
        name: locale
        schema:
          pattern: ^[a-z]{2}-[A-Z]{2}$
          type: string
      - in: path
        name: id
        required: true
        schema:
          example: XXX-XXXXX
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resp'
          description: OK
    put:
      parameters:
      - in: query
        name: locale
        schema:
          pattern: ^[a-z]{2}-[A-Z]{2}$
          type: string
      - in: path
        name: id
        required: true
        schema:
          example: XXX-XXXXX
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Req'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resp'
          description: OK
        "409":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Resp'
                type: array
          description: Conflict
components:
  schemas:
    Req:
      properties:
        amount:
          minimum: 0
          type: integer
        items:
          items:
            properties:
              count:
                minimum: 0
                type: integer
              name:
                type: string
            type: object
          nullable: true
          type: array
        string:
          type: string
      type: object
    Resp:
      properties:
        amount:
          minimum: 0
          type: integer
        id:
          example: XXX-XXXXX
          type: string
        items:
          items:
            properties:
              count:
                minimum: 0
                type: integer
              name:
                type: string
            type: object
          nullable: true
          type: array
        updated_at:
          format: date-time
          type: string
      type: object

Documentation

Overview

Package openapi provides tools and mappings for OpenAPI specs.

Index

• Constants
• func SanitizeMethodPath(method, pathPattern string) (cleanMethod string, cleanPath string, pathParams []string, err error)
• func WithContentType(contentType string) func(cu *ContentUnit)
• func WithHTTPStatus(httpStatus int) func(cu *ContentUnit)
• func WithOperationCtx(oc OperationContext, isProcessingResponse bool, in In) func(rc *jsonschema.ReflectContext)
• type ContentOption
  • func WithCustomize(customize func(cor ContentOrReference)) ContentOption
  • func WithReference(ref string) ContentOption
• type ContentOrReference
• type ContentUnit
  • func (c ContentUnit) FieldMapping(in In) map[string]string
  • func (c *ContentUnit) SetFieldMapping(in In, fieldToParamName map[string]string)
• type ContentUnitPreparer
• type In
• type JSONSchemaCallback
• type JSONSchemaWalker
• type OperationContext
  • func OperationCtx(rc *jsonschema.ReflectContext) (OperationContext, bool)
• type OperationInfo
• type OperationInfoReader
• type OperationState
• type Reflector
• type RequestBodyEnforcer
• type RequestJSONBodyEnforcer
• type SpecSchema

Constants

const (
	InPath     = In("path")
	InQuery    = In("query")
	InHeader   = In("header")
	InCookie   = In("cookie")
	InFormData = In("formData")
	InBody     = In("body")
)

In values enumeration.

Functions

func SanitizeMethodPath

func SanitizeMethodPath(method, pathPattern string) (cleanMethod string, cleanPath string, pathParams []string, err error)

SanitizeMethodPath validates method and parses path element names.

func WithContentType

func WithContentType(contentType string) func(cu *ContentUnit)

WithContentType is a ContentUnit option.

func WithHTTPStatus

func WithHTTPStatus(httpStatus int) func(cu *ContentUnit)

WithHTTPStatus is a ContentUnit option.

func WithOperationCtx

func WithOperationCtx(oc OperationContext, isProcessingResponse bool, in In) func(rc *jsonschema.ReflectContext)

WithOperationCtx is a jsonschema.ReflectContext option.

Types

type ContentOption

type ContentOption func(cu *ContentUnit)

ContentOption configures ContentUnit.

func WithCustomize

func WithCustomize(customize func(cor ContentOrReference)) ContentOption

WithCustomize is a ContentUnit option.

func WithReference

func WithReference(ref string) ContentOption

WithReference is a ContentUnit option.

type ContentOrReference

type ContentOrReference interface {
	SetReference(ref string)
}

ContentOrReference defines content entity that can be a reference.

type ContentUnit

type ContentUnit struct {
	Structure   interface{}
	ContentType string
	Format      string

	// HTTPStatus can have values 100-599 for single status, or 1-5 for status families (e.g. 2XX)
	HTTPStatus int

	// IsDefault indicates default response.
	IsDefault bool

	Description string

	// Customize allows fine control over prepared content entities.
	// The cor value can be asserted to one of these types:
	// *openapi3.RequestBodyOrRef
	// *openapi3.ResponseOrRef
	// *openapi31.RequestBodyOrReference
	// *openapi31.ResponseOrReference
	Customize func(cor ContentOrReference)
	// contains filtered or unexported fields
}

ContentUnit defines HTTP content.

func (ContentUnit) FieldMapping

func (c ContentUnit) FieldMapping(in In) map[string]string

FieldMapping returns custom field mapping.

func (*ContentUnit) SetFieldMapping

func (c *ContentUnit) SetFieldMapping(in In, fieldToParamName map[string]string)

SetFieldMapping sets custom field mapping.

type ContentUnitPreparer

type ContentUnitPreparer interface {
	SetupContentUnit(cu *ContentUnit)
}

ContentUnitPreparer defines self-contained ContentUnit.

type In

type In string

In defines value location in HTTP content.

type JSONSchemaCallback

type JSONSchemaCallback func(in In, paramName string, schema *jsonschema.SchemaOrBool, required bool) error

JSONSchemaCallback is a user function called by JSONSchemaWalker.

type JSONSchemaWalker

type JSONSchemaWalker interface {
	ResolveJSONSchemaRef(ref string) (s jsonschema.SchemaOrBool, found bool)
	WalkRequestJSONSchemas(method string, cu ContentUnit, cb JSONSchemaCallback, done func(oc OperationContext)) error
	WalkResponseJSONSchemas(cu ContentUnit, cb JSONSchemaCallback, done func(oc OperationContext)) error
}

JSONSchemaWalker can extract JSON schemas (for example, for validation purposes) from a ContentUnit.

type OperationContext

type OperationContext interface {
	OperationInfo
	OperationInfoReader
	OperationState

	Method() string
	PathPattern() string

	Request() []ContentUnit
	Response() []ContentUnit

	AddReqStructure(i interface{}, options ...ContentOption)
	AddRespStructure(o interface{}, options ...ContentOption)

	UnknownParamsAreForbidden(in In) bool
}

OperationContext defines operation and processing state.

func OperationCtx

func OperationCtx(rc *jsonschema.ReflectContext) (OperationContext, bool)

OperationCtx retrieves operation context from reflect context.

type OperationInfo

type OperationInfo interface {
	SetTags(tags ...string)
	SetIsDeprecated(isDeprecated bool)
	SetSummary(summary string)
	SetDescription(description string)
	SetID(operationID string)

	AddSecurity(securityName string, scopes ...string)
}

OperationInfo extends OperationContext with general information.

type OperationInfoReader

type OperationInfoReader interface {
	Tags() []string
	IsDeprecated() bool
	Summary() string
	Description() string
	ID() string
}

OperationInfoReader exposes current state of operation context.

type OperationState

type OperationState interface {
	IsProcessingResponse() bool
	ProcessingIn() In

	SetIsProcessingResponse(isProcessingResponse bool)
	SetProcessingIn(in In)
}

OperationState extends OperationContext with processing state information.

type Reflector

type Reflector interface {
	JSONSchemaWalker

	NewOperationContext(method, pathPattern string) (OperationContext, error)
	AddOperation(oc OperationContext) error

	SpecSchema() SpecSchema
	JSONSchemaReflector() *jsonschema.Reflector
}

Reflector defines OpenAPI reflector behavior.

type RequestBodyEnforcer

type RequestBodyEnforcer interface {
	ForceRequestBody()
}

RequestBodyEnforcer enables request body for GET and HEAD methods.

Should be implemented on input structure, function body can be empty. Forcing request body is not recommended and should only be used for backwards compatibility.

type RequestJSONBodyEnforcer

type RequestJSONBodyEnforcer interface {
	ForceJSONRequestBody()
}

RequestJSONBodyEnforcer enables JSON request body for structures with `formData` tags.

Should be implemented on input structure, function body can be empty.

type SpecSchema

type SpecSchema interface {
	Title() string
	Description() string
	Version() string

	SetTitle(t string)
	SetDescription(d string)
	SetVersion(v string)

	SetHTTPBasicSecurity(securityName string, description string)
	SetAPIKeySecurity(securityName string, fieldName string, fieldIn In, description string)
	SetHTTPBearerTokenSecurity(securityName string, format string, description string)
}

SpecSchema abstracts OpenAPI schema implementation to generalize multiple revisions.