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

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

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.

convert from string to builtin types (wraps strconv)

require ./typeutils (test dependency)

| | fileutils | file utilities | | | jsonname | JSON utilities (deprecated) | infer JSON names from go properties

use github.com/go-openapi/jsonpointer/jsonname instead | | 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

| | pools | utilities to work with sync.Pools | | | 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.

```go 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