openapi

package module
v1.0.7 Latest Latest
Warning

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

 Go to latest Published: Apr 2, 2025 License: MIT Imports: 15 Imported by: 4

README

OPENAPI

Document a REST API with an OpenAPI 3.0 specification.

  • Code, not configuration.
  • No magic comments, tags, or decorators.
  • Use with or without a Go web framework.
  • Populates schema automatically using reflection.

This project is based on https://github.com/a-h/rest by Adrian Hesketh.

Copyright (c) [2025] [Korbin]

This software is licensed under the MIT License. See the LICENSE file for details.

Why would I want to use this?

  • Add OpenAPI documentation to an API.
    • Create a swagger.json or swagger.yaml file.
  • Serve the Swagger UI to customers.

Examples

See the ./examples directory for complete examples.

Create an OpenAPI 3.0 (swagger) file
// Configure the models.
api := openapi.NewAPI("messages")
api.StripPkgPaths = []string{"github.com/ihezebin/openapi/example", "github.com/a-h/respond"}

api.Get("/topic/{id}").
  HasPathParameter("id", openapi.PathParam{
   Description: "id of the topic",
   Regexp:      `\d+`,
  }).
  HasResponseModel(http.StatusOK, openapi.ModelOf[models.Body[models.Topic]]()).
  HasResponseModel(http.StatusInternalServerError, openapi.ModelOf[models.Body[map[string]string]]()).
  HasTags([]string{"Topic"}).
  HasDescription("Get one topic by id").
  HasSummary("getOneTopic").
  HasHeaderParameter("Authorization", openapi.HeaderParam{
   Description: "Bearer token",
   Required:    true,
   Type:        openapi.PrimitiveTypeString,
  }).
  HasQueryParameter("limit", openapi.QueryParam{
   Description: "limit",
   Required:    true,
  }).
  HasResponseHeader(http.StatusOK, "Token", openapi.HeaderParam{
   Description: "token",
   Required:    true,
   Type:        openapi.PrimitiveTypeString,
  }).HasDeprecated(true)

api.Json()

Tasks

test
go test ./...
run-example

Dir: ./examples/stdlib

go run main.go

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type API 

type API struct {
	// Name of the API.
	Name string
	// Info of the API.
	Info openapi3.Info
	// Servers of the API.
	Servers []openapi3.Server
	// Routes of the API.
	// From patterns, to methods, to route.
	Routes map[Pattern]MethodToRoute
	// StripPkgPaths to strip from the type names in the OpenAPI output to avoid
	// leaking internal implementation details such as internal repo names.
	//
	// This increases the risk of type clashes in the OpenAPI output, i.e. two types
	// in different namespaces that are set to be stripped, and have the same type Name
	// could clash.
	//
	// Example values could be "github.com/ihezebin/openapi".
	StripPkgPaths []string

	// KnownTypes are added to the OpenAPI specification output.
	// The default implementation:
	//   Maps time.Time to a string.
	KnownTypes map[reflect.Type]openapi3.Schema

	// ApplyCustomSchemaToType callback to customise the OpenAPI specification for a given type.
	// Apply customisation to a specific type by checking the t parameter.
	// Apply customisations to all types by ignoring the t parameter.
	ApplyCustomSchemaToType func(t reflect.Type, s *openapi3.Schema)
	// contains filtered or unexported fields
}

API is a model of a REST API's routes, along with their request and response types.

func NewAPI 

func NewAPI(name string, opts ...APIOpts) *API

NewAPI creates a new API from the router.

func (*API) Connect 

func (api *API) Connect(pattern string) (r *Route)

Connect defines a CONNECT request route for the given pattern.

func (*API) Delete 

func (api *API) Delete(pattern string) (r *Route)

Delete defines a DELETE request route for the given pattern.

func (*API) Get 

func (api *API) Get(pattern string) (r *Route)

Get defines a GET request route for the given pattern.

func (*API) Head 

func (api *API) Head(pattern string) (r *Route)

Head defines a HEAD request route for the given pattern.

func (*API) Json 

func (api *API) Json() ([]byte, error)

Json creates a JSON representation of the OpenAPI specification.

func (*API) Merge 

func (api *API) Merge(r Route)

Merge route data into the existing configuration. This is typically used by adapters, such as the chiadapter to take information that the router already knows and add it to the specification.

func (*API) Options 

func (api *API) Options(pattern string) (r *Route)

Options defines an OPTIONS request route for the given pattern.

func (*API) Patch 

func (api *API) Patch(pattern string) (r *Route)

Patch defines a PATCH request route for the given pattern.

func (*API) Post 

func (api *API) Post(pattern string) (r *Route)

Post defines a POST request route for the given pattern.

func (*API) Put 

func (api *API) Put(pattern string) (r *Route)

Put defines a PUT request route for the given pattern.

func (*API) RegisterModel 

func (api *API) RegisterModel(model Model, opts ...ModelOpts) (name string, schema *openapi3.Schema, err error)

RegisterModel allows a model to be registered manually so that additional configuration can be applied. The schema returned can be modified as required.

func (*API) Route 

func (api *API) Route(method, pattern string) (r *Route)

Route upserts a route to the API definition.

func (*API) Spec 

func (api *API) Spec() (spec *openapi3.T, err error)

Spec creates an OpenAPI 3.0 specification document for the API.

func (*API) Trace 

func (api *API) Trace(pattern string) (r *Route)

Trace defines an TRACE request route for the given pattern.

func (*API) Yaml 

func (api *API) Yaml() ([]byte, error)

Yaml creates a YAML representation of the OpenAPI specification.

type APIOpts 

type APIOpts func(*API)

func WithApplyCustomSchemaToType 

func WithApplyCustomSchemaToType(f func(t reflect.Type, s *openapi3.Schema)) APIOpts

WithApplyCustomSchemaToType enables customisation of types in the OpenAPI specification. Apply customisation to a specific type by checking the t parameter. Apply customisations to all types by ignoring the t parameter.

func WithInfo added in v1.0.5 

func WithInfo(info openapi3.Info) APIOpts

func WithServer added in v1.0.5 

func WithServer(servers ...openapi3.Server) APIOpts

type CustomSchemaApplier 

type CustomSchemaApplier interface {
	ApplyCustomSchema(s *openapi3.Schema)
}

CustomSchemaApplier is a type that customises its OpenAPI schema.

type HeaderParam added in v1.0.1 

type HeaderParam struct {
	// Description of the param
	Description string
	// Required sets whether the header must be present
	Required bool
	// Type of the param (string, number, integer, boolean)
	Type PrimitiveType
	// ApplyCustomSchema customises the OpenAPI schema for the header parameter
	ApplyCustomSchema func(s *openapi3.Parameter)
}

HeaderParam is a parameter that's used in HTTP headers

type Method 

type Method string

Method is the HTTP method of the route, e.g. http.MethodGet

type MethodToRoute 

type MethodToRoute map[Method]*Route

MethodToRoute maps from a HTTP method to a Route.

type Model 

type Model struct {
	Type reflect.Type
	// contains filtered or unexported fields
}

Model is a model used in one or more routes.

func ModelFromType added in v1.0.3 

func ModelFromType(t reflect.Type) Model

ModelFromType creates a model of type t.

func ModelOf 

func ModelOf[T any]() Model

ModelOf creates a model of type T.

func (Model) ApplyCustomSchema 

func (m Model) ApplyCustomSchema(s *openapi3.Schema)

type ModelOpts 

type ModelOpts func(s *openapi3.Schema)

ModelOpts defines options that can be set when registering a model.

func WithDescription 

func WithDescription(desc string) ModelOpts

WithDescription sets the description field on the schema.

func WithEnumConstants 

func WithEnumConstants[T ~string | constraints.Integer]() ModelOpts

WithEnumConstants sets the property to be an enum containing the values of the type found in the package.

func WithEnumValues 

func WithEnumValues[T ~string | constraints.Integer](values ...T) ModelOpts

WithEnumValues sets the property to be an enum value with the specific values.

func WithNullable 

func WithNullable() ModelOpts

WithNullable sets the nullable field to true.

type Models 

type Models struct {
	Request         Model
	Responses       map[int]Model
	ResponseHeaders map[int]map[string]HeaderParam
}

Models defines the models used by a route.

type Params 

type Params struct {
	// Path parameters are used in the path of the URL, e.g. /users/{id} would
	// have a name of "id".
	Path map[string]PathParam
	// Query parameters are used in the querystring of the URL, e.g. /users/?sort={sortOrder} would
	// have a name of "sort".
	Query map[string]QueryParam
	// Header parameters are used in HTTP headers
	Header map[string]HeaderParam
}

Params is a route parameter.

type PathParam 

type PathParam struct {
	// Description of the param.
	Description string
	// Regexp is a regular expression used to validate the param.
	// An empty string means that no validation is applied.
	Regexp string
	// Type of the param (string, number, integer, boolean).
	Type PrimitiveType
	// ApplyCustomSchema customises the OpenAPI schema for the path parameter.
	ApplyCustomSchema func(s *openapi3.Parameter)
}

PathParam is a paramater that's used in the path of a URL.

type Pattern 

type Pattern string

Pattern of the route, e.g. /posts/list, or /users/{id}

type PrimitiveType 

type PrimitiveType string
const (
	PrimitiveTypeString  PrimitiveType = "string"
	PrimitiveTypeBool    PrimitiveType = "boolean"
	PrimitiveTypeInteger PrimitiveType = "integer"
	PrimitiveTypeFloat64 PrimitiveType = "number"
)

type QueryParam 

type QueryParam struct {
	// Description of the param.
	Description string
	// Regexp is a regular expression used to validate the param.
	// An empty string means that no validation is applied.
	Regexp string
	// Required sets whether the querystring parameter must be present in the URL.
	Required bool
	// AllowEmpty sets whether the querystring parameter can be empty.
	AllowEmpty bool
	// Type of the param (string, number, integer, boolean).
	Type PrimitiveType
	// ApplyCustomSchema customises the OpenAPI schema for the query parameter.
	ApplyCustomSchema func(s *openapi3.Parameter)
}

QueryParam is a paramater that's used in the querystring of a URL.

type Route 

type Route struct {
	// Method is the HTTP method of the route, e.g. http.MethodGet
	Method Method
	// Pattern of the route, e.g. /posts/list, or /users/{id}
	Pattern Pattern
	// Params of the route.
	Params Params
	// Models used in the route.
	Models Models
	// Tags used in the route.
	Tags []string
	// OperationID for the route.
	OperationID string
	// Description for the route.
	Description string
	// Summary for the route.
	Summary string
	// Deprecated sets whether the route is deprecated.
	Deprecated bool
}

Route models a single API route.

func (*Route) HasDeprecated added in v1.0.2 

func (rm *Route) HasDeprecated(deprecated bool) *Route

HasDeprecated sets the deprecated for the route.

func (*Route) HasDescription 

func (rm *Route) HasDescription(description string) *Route

HasDescription sets the description for the route.

func (*Route) HasHeaderParameter added in v1.0.1 

func (rm *Route) HasHeaderParameter(name string, h HeaderParam) *Route

HasHeaderParameter configures a header parameter for the route

func (*Route) HasOperationID 

func (rm *Route) HasOperationID(operationID string) *Route

HasOperationID sets the OperationID for the route.

func (*Route) HasPathParameter 

func (rm *Route) HasPathParameter(name string, p PathParam) *Route

HasPathParameter configures a path parameter for the route.

func (*Route) HasQueryParameter 

func (rm *Route) HasQueryParameter(name string, q QueryParam) *Route

HasQueryParameter configures a query parameter for the route.

func (*Route) HasRequestModel 

func (rm *Route) HasRequestModel(request Model) *Route

HasResponseModel configures the request model of the route. Example: 

api.Post("/user").HasRequestModel(http.StatusOK, openapi.ModelOf[User]())

func (*Route) HasResponseHeader added in v1.0.1 

func (rm *Route) HasResponseHeader(status int, name string, h HeaderParam) *Route

HasResponseHeader 为指定状态码配置响应头

func (*Route) HasResponseModel 

func (rm *Route) HasResponseModel(status int, response Model) *Route

HasResponseModel configures a response for the route. Example: 

api.Get("/user").HasResponseModel(http.StatusOK, openapi.ModelOf[User]())

func (*Route) HasSummary 

func (rm *Route) HasSummary(summary string) *Route

HasSummary sets the summary for the route.

func (*Route) HasTags 

func (rm *Route) HasTags(tags []string) *Route

HasTags sets the tags for the route.

Source Files

View all Source files

Directories

Path Synopsis
examples
models
parser
parser/snapshot command
parser/tests/anonymous
parser/tests/chans
parser/tests/docs
parser/tests/enum
parser/tests/functions
parser/tests/functiontypes
parser/tests/generics
parser/tests/maps
parser/tests/pointers
parser/tests/privatetypes
parser/tests/publictypes

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.