README.md

Swag

---

A bunch of helper functions for go-openapi and go-swagger projects.

You may also use it standalone for your projects.

NOTE swag is one of the foundational building blocks of the go-openapi initiative.

Most repositories in github.com/go-openapi/... depend on it in some way. And so does our CLI tool github.com/go-swagger/go-swagger, as well as the code generated by this tool.

• Contents
• Dependencies
• Change log
• Licensing
• Note to contributors
• Roadmap

Announcements

• 2025-12-19 : new community chat on discord
  • a new discord community channel is available to be notified of changes and support users
  • our venerable Slack channel remains open, and will be eventually discontinued on 2026-03-31

You may join the discord community by clicking the invite link on the discord badge (also above).

Or join our Slack channel:

Status

API is stable.

Import this library in your project

go get github.com/go-openapi/swag/{module}

Or for backward compatibility:

go get github.com/go-openapi/swag

Contents

go-openapi/swag exposes a collection of relatively independent modules.

Moving forward, no additional feature will be added to the swag API directly at the root package level, which remains there for backward-compatibility purposes. All exported top-level features are now deprecated.

Child modules will continue to evolve and some new ones may be added in the future.

Module	Content	Main features
cmdutils	utilities to work with CLIs
conv	type conversion utilities	convert between values and pointers for any types convert from string to builtin types (wraps strconv) require ./typeutils (test dependency)
fileutils	file utilities
jsonname	JSON utilities	infer JSON names from go properties
jsonutils	JSON utilities	fast json concatenation read and write JSON from and to dynamic go data structures require github.com/mailru/easyjson
loading	file loading	load from file or http require ./yamlutils
mangling	safe name generation	name mangling for go
netutils	networking utilities	host, port from address
stringutils	string utilities	search in slice (with case-insensitive) split/join query parameters as arrays
typeutils	go types utilities	check the zero value for any type safe check for a nil value
yamlutils	YAML utilities	converting YAML to JSON loading YAML into a dynamic YAML document maintaining the original order of keys in YAML objects require ./jsonutils require github.com/mailru/easyjson require go.yaml.in/yaml/v3

---

Dependencies

The root module github.com/go-openapi/swag at the repo level maintains a few dependencies outside of the standard library.

• YAML utilities depend on go.yaml.in/yaml/v3
• JSON utilities depend on their registered adapter module:
  • by default, only the standard library is used
  • github.com/mailru/easyjson is now only a dependency for module github.com/go-openapi/swag/jsonutils/adapters/easyjson/json, for users willing to import that module.
  • integration tests and benchmarks use all the dependencies are published as their own module
• other dependencies are test dependencies drawn from github.com/stretchr/testify

Usage

How to explicitly register a dependency at runtime?

The following would maintain how JSON utilities proposed by swag used work, up to v0.24.1.

import (
  "github.com/go-openapi/swag/jsonutils/adapters"
  easyjson "github.com/go-openapi/swag/jsonutils/adapters/easyjson/json"
)

func init() {
    easyjson.Register(adapters.Registry)
}

Subsequent calls to jsonutils.ReadJSON() or jsonutils.WriteJSON() will switch to easyjson whenever the passed data structures implement the easyjson.Unmarshaler or easyjson.Marshaler respectively, or fallback to the standard library.

For more details, you may also look at our integration tests.

---

Note to contributors

All kinds of contributions are welcome.

This repo is a go mono-repo. See docs.

More general guidelines are available here.

Roadmap

See the current TODO list

Change log

See https://github.com/go-openapi/swag/releases

For pre-v0.26.0 releases, see release notes.

What coming next?

Moving forward, we want to :

• provide an implementation of the JSON adapter based on encoding/json/v2, for go1.25 builds.
• provide similar implementations for goccy/go-json and jsoniterator/go, and perhaps some other similar libraries may be interesting too.

Licensing

This library ships under the SPDX-License-Identifier: Apache-2.0.

Other documentation

• All-time contributors
• Contributing guidelines
• Maintainers documentation
• Code style

Cutting a new release

Maintainers can cut a new release by either:

• running this workflow
• or pushing a semver tag
  • signed tags are preferred
  • The tag message is prepended to release notes