openapispecconverter

package module

v0.0.0-...-12cc6dc Latest Latest Go to latest Published: Mar 27, 2025 License: MIT Imports: 5 Imported by: 0

README ¶

openapi-spec-converter

openapi-spec-converter converts between Swagger, OpenAPI 3.0, and OpenAPI 3.1 documents in JSON or YAML formats. This tool exists to bridge gaps between tools for various languages for generating client code where support for any of the above document types is inconsistent.

Usage

Run the spec converting with Docker like so:

docker run --rm -i openapi-spec-converter:latest

At the time of writing the following options are supported.

Usage: openapi-spec-converter [-h] [-f value] [-o value] [-t value] <input>
 -f, --format=value
             Output format: yaml or json [json]
 -h, --help  Print this help message
 -o, --output=value
             Output file (default stdout)
 -t, --target=value
             Target version: swagger, 3.0, or 3.1 [3.1]

The input file can be specified as - for stdin, or omitted if piping in a file. In the simplest usage, you might want to do the following to get a valid OpenAPI 3.1 spec from any format.

docker run --rm -i openapi-spec-converter:latest < file.json

The spec converter will output to JSON by default. You can pass -f yaml to change the output format to YAML.

Development

You can build the Docker image with the following command.

docker build -t openapi-spec-converter:latest .

If you want to work on the code locally, insure you have Go 1.24 installed, and use gopls as your language server.

go install "golang.org/dl/go1.24.1@latest"
go1.24.1 download
go install golang.org/x/tools/gopls@latest

You can run the program directly while testing with go run.

To run tests for the program, you'll need a recent Node and npm version. You can use the latest version with nvm like so.

nvm install node
nvm use node

# Ensure you have a somewhat recent version of Node and npm installed first.
npm install
./convert-and-validate-specs

Documentation ¶

Index ¶

func UnmarshalSwagger(data []byte, kinDoc *openapi2.T) error
type Operation
- func (operation *Operation) UnmarshalJSON(data []byte) error
type Parameter
- func (parameter *Parameter) UnmarshalJSON(data []byte) error
type PathItem
- func (pathItem *PathItem) UnmarshalJSON(data []byte) error
type SwaggerDoc
- func (doc *SwaggerDoc) UnmarshalJSON(data []byte) error

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func UnmarshalSwagger ¶

func UnmarshalSwagger(data []byte, kinDoc *openapi2.T) error

Unmarshal loads a YAML or JSON Swagger document into a kin-openapi representation.

Types ¶

type Operation ¶

type Operation struct {
	Extensions   map[string]any                 `json:"-" yaml:"-"`
	Summary      string                         `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description  string                         `json:"description,omitempty" yaml:"description,omitempty"`
	Deprecated   bool                           `json:"deprecated,omitempty" yaml:"deprecated,omitempty"`
	ExternalDocs *openapi3.ExternalDocs         `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	Tags         []string                       `json:"tags,omitempty" yaml:"tags,omitempty"`
	OperationID  string                         `json:"operationId,omitempty" yaml:"operationId,omitempty"`
	Parameters   []Parameter                    `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	Responses    map[string]*openapi2.Response  `json:"responses" yaml:"responses"`
	Consumes     []string                       `json:"consumes,omitempty" yaml:"consumes,omitempty"`
	Produces     []string                       `json:"produces,omitempty" yaml:"produces,omitempty"`
	Schemes      []string                       `json:"schemes,omitempty" yaml:"schemes,omitempty"`
	Security     *openapi2.SecurityRequirements `json:"security,omitempty" yaml:"security,omitempty"`
}

func (*Operation) UnmarshalJSON ¶

func (operation *Operation) UnmarshalJSON(data []byte) error

UnmarshalJSON sets Operation to a copy of data.

type Parameter ¶

type Parameter struct {
	Extensions       map[string]any      `json:"-" yaml:"-"`
	Ref              string              `json:"$ref,omitempty" yaml:"$ref,omitempty"`
	In               string              `json:"in,omitempty" yaml:"in,omitempty"`
	Name             string              `json:"name,omitempty" yaml:"name,omitempty"`
	Description      string              `json:"description,omitempty" yaml:"description,omitempty"`
	CollectionFormat string              `json:"collectionFormat,omitempty" yaml:"collectionFormat,omitempty"`
	Type             string              `json:"type,omitempty" yaml:"type,omitempty"`
	Format           string              `json:"format,omitempty" yaml:"format,omitempty"`
	Pattern          string              `json:"pattern,omitempty" yaml:"pattern,omitempty"`
	AllowEmptyValue  bool                `json:"allowEmptyValue,omitempty" yaml:"allowEmptyValue,omitempty"`
	Required         bool                `json:"required,omitempty" yaml:"required,omitempty"`
	UniqueItems      bool                `json:"uniqueItems,omitempty" yaml:"uniqueItems,omitempty"`
	ExclusiveMin     bool                `json:"exclusiveMinimum,omitempty" yaml:"exclusiveMinimum,omitempty"`
	ExclusiveMax     bool                `json:"exclusiveMaximum,omitempty" yaml:"exclusiveMaximum,omitempty"`
	Schema           *openapi2.SchemaRef `json:"schema,omitempty" yaml:"schema,omitempty"`
	Items            *openapi2.SchemaRef `json:"items,omitempty" yaml:"items,omitempty"`
	Enum             []any               `json:"enum,omitempty" yaml:"enum,omitempty"`
	MultipleOf       *float64            `json:"multipleOf,omitempty" yaml:"multipleOf,omitempty"`
	Minimum          *float64            `json:"minimum,omitempty" yaml:"minimum,omitempty"`
	Maximum          *float64            `json:"maximum,omitempty" yaml:"maximum,omitempty"`
	MaxLength        *uint64             `json:"maxLength,omitempty" yaml:"maxLength,omitempty"`
	MaxItems         *uint64             `json:"maxItems,omitempty" yaml:"maxItems,omitempty"`
	MinLength        uint64              `json:"minLength,omitempty" yaml:"minLength,omitempty"`
	MinItems         uint64              `json:"minItems,omitempty" yaml:"minItems,omitempty"`
	Default          any                 `json:"default,omitempty" yaml:"default,omitempty"`
}

func (*Parameter) UnmarshalJSON ¶

func (parameter *Parameter) UnmarshalJSON(data []byte) error

type PathItem ¶

type PathItem struct {
	Extensions map[string]any `json:"-" yaml:"-"`
	Delete     *Operation     `json:"delete,omitempty" yaml:"delete,omitempty"`
	Get        *Operation     `json:"get,omitempty" yaml:"get,omitempty"`
	Head       *Operation     `json:"head,omitempty" yaml:"head,omitempty"`
	Options    *Operation     `json:"options,omitempty" yaml:"options,omitempty"`
	Patch      *Operation     `json:"patch,omitempty" yaml:"patch,omitempty"`
	Post       *Operation     `json:"post,omitempty" yaml:"post,omitempty"`
	Put        *Operation     `json:"put,omitempty" yaml:"put,omitempty"`
	Parameters []Parameter    `json:"parameters,omitempty" yaml:"parameters,omitempty"`
}

func (*PathItem) UnmarshalJSON ¶

func (pathItem *PathItem) UnmarshalJSON(data []byte) error

UnmarshalJSON sets PathItem to a copy of data.

type SwaggerDoc ¶

type SwaggerDoc struct {
	Extensions          map[string]any                      `json:"-" yaml:"-"`
	Swagger             string                              `json:"swagger" yaml:"swagger"` // required
	Info                openapi3.Info                       `json:"info" yaml:"info"`       // required
	ExternalDocs        *openapi3.ExternalDocs              `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	Schemes             []string                            `json:"schemes,omitempty" yaml:"schemes,omitempty"`
	Consumes            []string                            `json:"consumes,omitempty" yaml:"consumes,omitempty"`
	Produces            []string                            `json:"produces,omitempty" yaml:"produces,omitempty"`
	Host                string                              `json:"host,omitempty" yaml:"host,omitempty"`
	BasePath            string                              `json:"basePath,omitempty" yaml:"basePath,omitempty"`
	Paths               map[string]PathItem                 `json:"paths,omitempty" yaml:"paths,omitempty"`
	Definitions         map[string]*openapi2.SchemaRef      `json:"definitions,omitempty" yaml:"definitions,omitempty"`
	Parameters          map[string]*Parameter               `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	Responses           map[string]*openapi2.Response       `json:"responses,omitempty" yaml:"responses,omitempty"`
	SecurityDefinitions map[string]*openapi2.SecurityScheme `json:"securityDefinitions,omitempty" yaml:"securityDefinitions,omitempty"`
	Security            openapi2.SecurityRequirements       `json:"security,omitempty" yaml:"security,omitempty"`
	Tags                openapi3.Tags                       `json:"tags,omitempty" yaml:"tags,omitempty"`
}

func (*SwaggerDoc) UnmarshalJSON ¶

func (doc *SwaggerDoc) UnmarshalJSON(data []byte) error

UnmarshalJSON sets T to a copy of data.

Source Files ¶

View all Source files

swaggerspec.go

Directories ¶

Path	Synopsis
cmd
openapi-spec-converter command

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL