go-openapi/swag
GitHub: go-openapi/swag
Stars: 221 | Forks: 52
# Swag
[][test-url] [][cov-url] [][vuln-scan-url] [][codeql-url]
[][release-url] [][gocard-url] [][codefactor-url] [][license-url]
[][godoc-url] [][discord-url] [][goversion-url]  
A bunch of helper functions for go-openapi and go-swagger projects.
You may also use it standalone for your projects.
* [Contents](#contents)
* [Dependencies](#dependencies)
* [Change log](#change-log)
* [Licensing](#licensing)
* [Note to contributors](#note-to-contributors)
* [Roadmap](#roadmap)
## Announcements
Or join our Slack channel: [![slack-badge]][slack-url]
## 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](jsonutils/adapters/testintegration/integration_suite_test.go#29). ## Roadmap See the current [TODO list](docs/TODOS.md) ## Change log See
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.
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](jsonutils/adapters/testintegration/integration_suite_test.go#29). ## Roadmap See the current [TODO list](docs/TODOS.md) ## Change log See
标签：EVTX分析