moby/vendor/github.com/go-openapi/swag/README.md

# Swag

<!-- Badges: status  -->
[![Tests][test-badge]][test-url] [![Coverage][cov-badge]][cov-url] [![CI vuln scan][vuln-scan-badge]][vuln-scan-url] [![CodeQL][codeql-badge]][codeql-url]
<!-- Badges: release & docker images  -->
<!-- Badges: code quality  -->
<!-- Badges: license & compliance -->
[![Release][release-badge]][release-url] [![Go Report Card][gocard-badge]][gocard-url] [![CodeFactor Grade][codefactor-badge]][codefactor-url] [![License][license-badge]][license-url]
<!-- Badges: documentation & support -->
<!-- Badges: others & stats -->
[![GoDoc][godoc-badge]][godoc-url] [![Discord Channel][discord-badge]][discord-url] [![go version][goversion-badge]][goversion-url] ![Top language][top-badge] ![Commits since latest release][commits-badge]

---

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](#contents)
* [Dependencies](#dependencies)
* [Change log](#change-log)
* [Licensing](#licensing)
* [Note to contributors](#note-to-contributors)
* [Roadmap](#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). [![Discord Channel][discord-badge]][discord-url]

## Status

API is stable.

## Import this library in your project

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

Or for backward compatibility:

```cmd
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<br />convert from string to builtin types (wraps `strconv`)<br />require `./typeutils` (test dependency)<br /> |
| `fileutils`   | file utilities | |
| `jsonname`    | JSON utilities | infer JSON names from `go` properties<br /> |
| `jsonutils`   | JSON utilities | fast json concatenation<br />read and write JSON from and to dynamic `go` data structures<br />~require `github.com/mailru/easyjson`~<br /> |
| `loading`     | file loading | load from file or http<br />require `./yamlutils`<br /> |
| `mangling`    | safe name generation | name mangling for `go`<br /> |
| `netutils`    | networking utilities | host, port from address<br /> |
| `stringutils` | `string` utilities | search in slice (with case-insensitive)<br />split/join query parameters as arrays<br /> |
| `typeutils`   | `go` types utilities | check the zero value for any type<br />safe check for a nil value<br /> |
| `yamlutils`   | YAML utilities | converting YAML to JSON<br />loading YAML into a dynamic YAML document<br />maintaining the original order of keys in YAML objects<br />require `./jsonutils`<br />~require `github.com/mailru/easyjson`~<br />require `go.yaml.in/yaml/v3`<br /> |

---

## 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](jsonutils/adapters/testintegration/integration_suite_test.go#29).

---

## Note to contributors

All kinds of contributions are welcome.

This repo is a go mono-repo. See [docs](docs/MAINTAINERS.md).

More general guidelines are available [here](.github/CONTRIBUTING.md).

## Roadmap

See the current [TODO list](docs/TODOS.md)

## Change log

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

For pre-v0.26.0 releases, see [release notes](./docs/NOTES.md).

**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.

<!--

## References

-->

## Licensing

This library ships under the [SPDX-License-Identifier: Apache-2.0](./LICENSE).

<!--
See the license [NOTICE](./NOTICE), which recalls the licensing terms of all the pieces of software
on top of which it has been built.
-->

<!--

## Limitations

-->

## Other documentation

* [All-time contributors](./CONTRIBUTORS.md)
* [Contributing guidelines][contributing-doc-site]
* [Maintainers documentation][maintainers-doc-site]
* [Code style][style-doc-site]

## Cutting a new release

Maintainers can cut a new release by either:

* running [this workflow](https://github.com/go-openapi/swag/actions/workflows/bump-release.yml)
* or pushing a semver tag
  * signed tags are preferred
  * The tag message is prepended to release notes

<!-- Badges: status  -->
[test-badge]: https://github.com/go-openapi/swag/actions/workflows/go-test.yml/badge.svg
[test-url]: https://github.com/go-openapi/swag/actions/workflows/go-test.yml
[cov-badge]: https://codecov.io/gh/go-openapi/swag/branch/master/graph/badge.svg
[cov-url]: https://codecov.io/gh/go-openapi/swag
[vuln-scan-badge]: https://github.com/go-openapi/swag/actions/workflows/scanner.yml/badge.svg
[vuln-scan-url]: https://github.com/go-openapi/swag/actions/workflows/scanner.yml
[codeql-badge]: https://github.com/go-openapi/swag/actions/workflows/codeql.yml/badge.svg
[codeql-url]: https://github.com/go-openapi/swag/actions/workflows/codeql.yml
<!-- Badges: release & docker images  -->
[release-badge]: https://badge.fury.io/gh/go-openapi%2Fswag.svg
[release-url]: https://badge.fury.io/gh/go-openapi%2Fswag
[gomod-badge]: https://badge.fury.io/go/github.com%2Fgo-openapi%2Fswag.svg
[gomod-url]: https://badge.fury.io/go/github.com%2Fgo-openapi%2Fswag
<!-- Badges: code quality  -->
[gocard-badge]: https://goreportcard.com/badge/github.com/go-openapi/swag
[gocard-url]: https://goreportcard.com/report/github.com/go-openapi/swag
[codefactor-badge]: https://img.shields.io/codefactor/grade/github/go-openapi/swag
[codefactor-url]: https://www.codefactor.io/repository/github/go-openapi/swag
<!-- Badges: documentation & support -->
[doc-badge]: https://img.shields.io/badge/doc-site-blue?link=https%3A%2F%2Fgoswagger.io%2Fgo-openapi%2F
[doc-url]: https://goswagger.io/go-openapi
[godoc-badge]: https://pkg.go.dev/badge/github.com/go-openapi/swag
[godoc-url]: http://pkg.go.dev/github.com/go-openapi/swag
[discord-badge]: https://img.shields.io/discord/1446918742398341256?logo=discord&label=discord&color=blue
[discord-url]: https://discord.gg/FfnFYaC3k5

<!-- Badges: license & compliance -->
[license-badge]: http://img.shields.io/badge/license-Apache%20v2-orange.svg
[license-url]: https://github.com/go-openapi/swag/?tab=Apache-2.0-1-ov-file#readme
<!-- Badges: others & stats -->
[goversion-badge]: https://img.shields.io/github/go-mod/go-version/go-openapi/swag
[goversion-url]: https://github.com/go-openapi/swag/blob/master/go.mod
[top-badge]: https://img.shields.io/github/languages/top/go-openapi/swag
[commits-badge]: https://img.shields.io/github/commits-since/go-openapi/swag/latest
<!-- Organization docs -->
[contributing-doc-site]: https://go-openapi.github.io/doc-site/contributing/contributing/index.html
[maintainers-doc-site]: https://go-openapi.github.io/doc-site/maintainers/index.html
[style-doc-site]: https://go-openapi.github.io/doc-site/contributing/style/index.html