go-swagger README

The project's README from github.com/go-swagger/go-swagger. As one markdown file: README.md.

Swagger 2.0

Tests Coverage CI vuln scan CodeQL

Release Container Registry on Quay.io Container Registry on Github

CodeFactor Grade

License Open SSF Scorecard OpenSSF Best Practices OpenSSF Baseline OSS licences status

Documentation GoDoc Discord Channel go version Top language Commits since latest release


This project contains a golang implementation of Swagger 2.0 (aka OpenAPI 2.0). It provide tools to work with swagger specifications.

Swagger is a simple yet powerful representation of your RESTful API.

Announcements

You may join the discord community by clicking the invite link on the discord badge. Discord Channel.

Documentation

https://goswagger.io

Features

go-swagger brings to the go community a complete suite of fully-featured, high-performance, API components to work with a Swagger API: server, client and data model.

Our focus with code generation is to produce idiomatic, fast go code, which plays nice with golint, go vet etc.

More details.

Project status

This project supports OpenAPI 2.0. At this moment it does not support OpenAPI 3.x.

go-swagger is now feature complete and has stabilized its API.

Most features and building blocks are now in a stable state, with a rich set of CI tests.

The go-openapi community actively continues bringing fixes and enhancements to this code base.

There is still much room for improvement: contributors and PR's are welcome. You may also get in touch with maintainers on our Discord Channel.

Installing

go install github.com/go-swagger/go-swagger/cmd/swagger@latest

go-swagger is also available as binary or docker releases as well as from source: more details.

Try it

Try go-swagger in a free online workspace using Gitpod:

Open in Gitpod

Security

go-swagger turns an OpenAPI 2.0 specification into source code. Treat a specification like any other untrusted input: if you obtained it from a remote or untrusted location, review its contents before generating code from it.

The generator never executes the spec, and the generated code runs only when you build and import it. We have hardened the generators against an adversarial spec that tries to inject unwanted Go into the artifacts it produces — identifiers, struct tags, doc comments and CLI string literals are sanitized or escaped — which substantially reduces the exposure. It is not, however, a substitute for reviewing what you generate. In particular:

When in doubt, generate into a scratch directory, read the diff, and only then wire it into your build.

Licensing

The toolkit itself is licensed under an Apache Software License 2.0: SPDX-License-Identifier: Apache-2.0.

Just like swagger, this does not cover code generated by the toolkit. That code is entirely yours to license however you see fit.

Licence scan on dependencies

FOSSA Status

go-swagger (go-swagger/go-swagger)

Searching Database…

这是什么?这是面向 Swagger 2.0(OpenAPI 2.0)的 Go 工具包:一整套功能完备、高性能的组件和工具,用于处理 RESTful API 的 swagger 规范。
那它是需要安装运行的东西,还是导入使用的库?两者都是。'swagger' 命令行工具是用来生成代码的,而它底层的各个 Go API 组件(服务端、客户端、数据模型)则是你的项目所使用的库。
怎么获取它?从发布页面下载预编译的二进制文件,运行 Docker 镜像(发布在 Quay.io 和 GHCR 上),或者从源码构建。你也可以在免费的 Gitpod 工作区里试用,什么都不用安装。
使用它需要安装 Go 吗?运行生成器本身不需要:它以独立二进制文件的形式发布。但它生成的代码是 Go 代码,所以你需要 Go 工具链来编译和运行它生成的东西。
它能处理 OpenAPI 3 的规范吗?不能——它只支持 Swagger/OpenAPI 2.0,目前不支持 OpenAPI 3.x。
这是给谁用的——只面向 Go 开发者吗?是的,它就是为 Go 社区打造的:它生成地道的 Go 代码,其组件本身也是 Go 库,适合用 Go 构建 REST API 的团队。
它能在哪些平台上运行?它是一个跨平台的 Go 二进制程序,提供 Windows、macOS 和 Linux 版本,另外在 Quay.io 和 GHCR 上还有 Docker 镜像。
它的许可证有什么特别之处吗?这个工具包采用 Apache-2.0 许可证,但这只覆盖工具包本身:生成的代码完全归你所有,你想用什么许可证都可以。
它能根据规范生成什么?直接根据 swagger 规范生成 Go 服务端、Go 客户端,以及一个命令行工具(仍处于 alpha 阶段)。它还能反向工作——从带注解的 Go 代码生成 swagger 规范——并支持大部分 jsonschema 和 swagger 特性,包括多态。
我能自定义它生成的代码吗?可以,通过 vendor 扩展和可自定义的模板来实现。它宣称的目标是生成地道、快速的 Go 代码,并且能顺利通过 golint 和 go vet 的检查。
从网上找到的规范生成代码安全吗?要把任何规范都当作不可信的输入。生成器从不执行规范,并会对标识符、struct 标签、文档注释和命令行字符串字面量做清理,但仍需检查生成结果:远程 $refs 会被合并进你的代码,而且 x-go-type 扩展可以让规范导入任意包。
这个项目还在维护吗?是的——它功能已经完整,API 稳定,go-openapi 社区也在持续发布修复和改进:v0.36.0 到 v0.36.4 等版本于 2026 年年中发布,其中包括一个为修复 Go 严重漏洞而重新构建的 Docker 镜像。
Creator
go-swagger
Size
55.4 MB
Stars
10K
Age
11y
Commits · 90 Days