go-restful-openapi

December 24, 2025 · View on GitHub

Generate OpenAPI specifications from go-restful WebServices.

Supported OpenAPI versions:

OpenAPI 3.2.0, 3.1.x, 3.0.x
OpenAPI 2.0 (Swagger)

Installation

go get github.com/emicklei/go-restful-openapi/v2

Quick Start

OpenAPI 3.x (Recommended)

import (
    restfulspec "github.com/emicklei/go-restful-openapi/v2"
    restful "github.com/emicklei/go-restful/v3"
)

func main() {
    ws := new(restful.WebService)
    ws.Path("/users")
    ws.Route(ws.GET("/").To(listUsers).
        Doc("List all users").
        Writes([]User{}))

    config := restfulspec.Config{
        WebServices: []*restful.WebService{ws},
        OASVersion:  restfulspec.OASVersion320,
        Servers: []*restfulspec.Server{
            {URL: "https://api.example.com"},
        },
        Info: &restfulspec.Info{
            Title:       "User API",
            Description: "API for managing users",
            Version:     "1.0.0",
        },
    }

    doc, err := restfulspec.BuildOAS3(config)
    if err != nil {
        log.Fatal(err)
    }
    // Serialize to JSON/YAML, serve via endpoint, write to file, etc.
}

OpenAPI 2.0

config := restfulspec.Config{
    WebServices: []*restful.WebService{ws},
    Host:        "api.example.com",
    Schemes:     []string{"https"},
}

doc, err := restfulspec.BuildOAS2(config)
if err != nil {
    log.Fatal(err)
}

API

Function	Description
`BuildOAS3(config) (*OAS3Document, error)`	Build an OpenAPI 3.x document
`BuildOAS2(config) (*OAS2Document, error)`	Build an OpenAPI 2.0 document

OAS Version Constants

restfulspec.OASVersion320  // OpenAPI 3.2.0 (default)
restfulspec.OASVersion311  // OpenAPI 3.1.1
restfulspec.OASVersion310  // OpenAPI 3.1.0
restfulspec.OASVersion304  // OpenAPI 3.0.4
restfulspec.OASVersion303  // OpenAPI 3.0.3
restfulspec.OASVersion302  // OpenAPI 3.0.2
restfulspec.OASVersion301  // OpenAPI 3.0.1
restfulspec.OASVersion300  // OpenAPI 3.0.0
restfulspec.OASVersion20   // OpenAPI 2.0 (Swagger)

Configuration

type Config struct {
    // Required: services to document
    WebServices []*restful.WebService

    // API metadata
    Info       *Info      // Title, description, version, contact, license
    APIVersion string     // Alternative to Info.Version

    // Server configuration
    Servers []*Server     // OAS 3.x server objects
    Host    string        // OAS 2.0 host (also used to generate Server for OAS 3.x)
    Schemes []string      // OAS 2.0 schemes (used with Host for OAS 3.x Server)

    // OAS version (for BuildOAS3, defaults to 3.2.0)
    OASVersion OASVersion

    // Schema naming
    SchemaNaming          SchemaNamingStrategy  // How to name schemas
    GenericNaming         GenericNamingStrategy // How to format generic types
    SemanticDeduplication bool                  // Consolidate identical schemas
    SchemaNameFunc        SchemaNameFunc        // Custom naming function

    // Post-build customization
    PostBuildOAS2Handler func(*OAS2Document)
    PostBuildOAS3Handler func(*OAS3Document)
}

Schema Naming Strategies

Control how Go types are converted to schema names:

Strategy	Example Output
`SchemaNamingDefault`	`models.User`
`SchemaNamingTypeOnly`	`User`
`SchemaNamingPascalCase`	`ModelsUser`
`SchemaNamingCamelCase`	`modelsUser`
`SchemaNamingSnakeCase`	`models_user`
`SchemaNamingKebabCase`	`models-user`
`SchemaNamingFullPath`	`github.com_org_models_User`

config := restfulspec.Config{
    WebServices:  []*restful.WebService{ws},
    SchemaNaming: restfulspec.SchemaNamingTypeOnly,
}

Generic Naming Strategies

Control how generic type parameters appear in schema names:

Strategy	Example Output
`GenericNamingUnderscore`	`Response_User_`
`GenericNamingOf`	`ResponseOfUser`
`GenericNamingFor`	`ResponseForUser`
`GenericNamingAngleBrackets`	`Response<User>`
`GenericNamingFlattened`	`ResponseUser`

Struct Tags

Customize schema generation using struct tags on your model types.

Tag	Description	Example
`json`	Field name in JSON	`json:"user_name"`
`description`	Field description	`description:"User's email"`
`type`	Override type	`type:"string"` or `type:"[]string"`
`format`	OpenAPI format	`format:"email"`
`enum`	Allowed values (pipe-separated)	`enum:"active\|inactive"`
`default`	Default value	`default:"active"`
`example`	Example value	`example:"user@example.com"`
`minimum`	Minimum numeric value	`minimum:"0"`
`maximum`	Maximum numeric value	`maximum:"100"`
`optional`	Mark as not required	`optional:"true"`
`unique`	Array items must be unique	`unique:"true"`
`readOnly`	Field is read-only	`readOnly:"true"`
`x-nullable`	Field can be null	`x-nullable:"true"`
`modelDescription`	Model description	`modelDescription:"A user"`

Example

type User struct {
    ID        int       `json:"id" readOnly:"true"`
    Email     string    `json:"email" format:"email" description:"User's email address"`
    Name      string    `json:"name" description:"Full name" example:"John Doe"`
    Age       int       `json:"age,omitempty" minimum:"0" maximum:"150"`
    Status    string    `json:"status" enum:"active|inactive|pending" default:"active"`
    CreatedAt time.Time `json:"created_at" readOnly:"true"`
}

Post-Build Customization

Modify the generated document before it's returned:

config := restfulspec.Config{
    WebServices: []*restful.WebService{ws},
    PostBuildOAS3Handler: func(doc *restfulspec.OAS3Document) {
        // Add security schemes, tags, or any other customization
        doc.Components.SecuritySchemes = map[string]*SecurityScheme{
            "bearerAuth": {
                Type:   "http",
                Scheme: "bearer",
            },
        }
    },
}

Semantic Deduplication

When enabled, structurally identical schemas are consolidated into a single definition:

config := restfulspec.Config{
    WebServices:           []*restful.WebService{ws},
    SemanticDeduplication: true,
}

Legacy API

The following API uses go-openapi/spec types and only supports OpenAPI 2.0. Consider migrating to BuildOAS2 or BuildOAS3 for new projects.

// BuildSwagger returns a *spec.Swagger (go-openapi/spec types)
swagger := restfulspec.BuildSwagger(config)

// NewOpenAPIService creates a WebService that serves the spec at config.APIPath
restful.Add(restfulspec.NewOpenAPIService(config))

Legacy Configuration Options

These options only apply to BuildSwagger and NewOpenAPIService:

type Config struct {
    // Path to serve the spec (e.g., "/apidocs.json")
    APIPath string

    // Disable CORS headers on the spec endpoint
    DisableCORS bool

    // Customize the Swagger object after generation
    PostBuildSwaggerObjectHandler func(*spec.Swagger)

    // Custom type format mapping
    SchemaFormatHandler MapSchemaFormatFunc

    // Custom type name mapping
    ModelTypeNameHandler MapModelTypeNameFunc

    // Custom definition name handling
    DefinitionNameHandler DefinitionNameHandlerFunc
}

Go Modules

Version v2 of this package requires:

Go 1.18+
github.com/emicklei/go-restful/v3

import (
    restfulspec "github.com/emicklei/go-restful-openapi/v2"
    restful "github.com/emicklei/go-restful/v3"
)

For go-restful v2, use v1 of this package (OpenAPI 2.0 only):

import (
    restfulspec "github.com/emicklei/go-restful-openapi"
    restful "github.com/emicklei/go-restful/v2"
)

Dependencies

go-restful v3 - REST framework
oastools - OpenAPI document builder

License

MIT License. Contributions welcome.

2017-2024, ernestmicklei.com