Install and CLI reference¶
Install¶
Go toolchain
go install github.com/parvez3019/go-swagger3@latest
If you get command not found: go-swagger3, add your Go bin directory to PATH:
export PATH="$(go env GOPATH)/bin:$PATH"
Prebuilt binary. Download an archive for Linux, macOS or Windows (amd64/arm64) from the
latest release and put go-swagger3 on your PATH.
Docker (linux/amd64 and linux/arm64)
docker run -t --rm -v $(pwd):/app -w /app parvez3019/go-swagger3:latest --module-path . --output oas.json
Check the installed version with go-swagger3 --version.
Generate a spec¶
Run from the directory that contains your go.mod:
# go.mod and main.go are in the same directory
go-swagger3 --module-path . --output oas.json --schema-without-pkg
# main.go is somewhere else
go-swagger3 --module-path . --main-file-path ./cmd/api/main.go --output oas.json --schema-without-pkg
# YAML instead of JSON
go-swagger3 --module-path . --output oas.yaml --schema-without-pkg --generate-yaml
With Docker, pass the same flags after the image name:
docker run -t --rm -v $(pwd):/app -w /app parvez3019/go-swagger3:latest \
--module-path . --main-file-path ./cmd/api/main.go --output oas.json --schema-without-pkg
Flags¶
| Flag | Description |
|---|---|
--module-path |
Directory of the Go module to scan for @ annotations |
--main-file-path |
File with the service-level annotations (@Title, @Version, …); defaults to main.go in the module path |
--handler-path |
Only scan handler comments under this path |
--output |
Output file (default oas.json) |
--generate-yaml |
Write YAML instead of JSON |
--schema-without-pkg |
Name schemas without the package prefix (User instead of model.User) |
--exclude dir1,dir2 |
Comma-separated paths to skip while walking the module |
--quiet |
Only print warnings and errors |
--strict |
Treat Go parsing warnings as fatal errors |
--debug |
Verbose logs |
--version, -v |
Print the version |
Note
Keep handler annotations out of the file passed as --main-file-path (by default main.go).
Service-level tags such as @Title are read from every comment in that file, so a handler's @Title there
overrides the API title.
Format annotations¶
Align @ annotations in Go source files, like go fmt / swag fmt:
go-swagger3 fmt -d ./