Skip to content

Commit

Permalink
merge master to v2 (#1903)
Browse files Browse the repository at this point in the history
* Update README_zh-CN.md (#1545)

remove repeat net/http

* Add option to set template delimiters (#1499)

* Add template action delimiter cli flag

* Add delims to generator config and template

Also adds tests using the "quote" test as a base. This has to have a
custom Instance name or it will clash with the "quotes" one and panic
since it will have registered two "swagger" instances in the package
test.

* Add testdata for custom delim flags

Based on the "quote" testdata.

* Add delims to the spec, with tests.

Make sure we don't add delims if they are empty. This shouldn't be
possible, but might as well be safe.

* Go mod tidy and sum update

* Make the CLI experience a bit cleaner

* Revert go.mod and sum

* Update readme

* fix bug: enums of explicit type conversion (#1556)

Signed-off-by: sdghchj <[email protected]>

* add retract to fix proxy cache caused by accidentally pushed tags (#1562)

* add retract caused by accidentally pushed tags

* update version to match new tag version

---------

Co-authored-by: Tobias Theel <[email protected]>

* docs: doc to pt Add option to set template delims. (#1563)

* fix: lint error for generated docs.go (#1583)

Co-authored-by: wanglonghui7 <[email protected]>

* fix bug: enums of underscored number (#1581)

Signed-off-by: sdghchj <[email protected]>

* fix using tab (\t) as separator for custom type names (#1594)

* chore(deps): bump github.com/gin-gonic/gin (#1598)

Bumps [github.com/gin-gonic/gin](https://github.com/gin-gonic/gin) from 1.7.7 to 1.9.1.
- [Release notes](https://github.com/gin-gonic/gin/releases)
- [Changelog](https://github.com/gin-gonic/gin/blob/master/CHANGELOG.md)
- [Commits](gin-gonic/gin@v1.7.7...v1.9.1)

---
updated-dependencies:
- dependency-name: github.com/gin-gonic/gin
  dependency-type: direct:production
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* chore(deps): bump github.com/gin-gonic/gin in /example/celler (#1599)

Bumps [github.com/gin-gonic/gin](https://github.com/gin-gonic/gin) from 1.7.7 to 1.9.1.
- [Release notes](https://github.com/gin-gonic/gin/releases)
- [Changelog](https://github.com/gin-gonic/gin/blob/master/CHANGELOG.md)
- [Commits](gin-gonic/gin@v1.7.7...v1.9.1)

---
updated-dependencies:
- dependency-name: github.com/gin-gonic/gin
  dependency-type: direct:production
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* chore(deps): bump github.com/gin-gonic/gin in /example/go-module-support (#1600)

Bumps [github.com/gin-gonic/gin](https://github.com/gin-gonic/gin) from 1.7.7 to 1.9.1.
- [Release notes](https://github.com/gin-gonic/gin/releases)
- [Changelog](https://github.com/gin-gonic/gin/blob/master/CHANGELOG.md)
- [Commits](gin-gonic/gin@v1.7.7...v1.9.1)

---
updated-dependencies:
- dependency-name: github.com/gin-gonic/gin
  dependency-type: direct:production
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* fix required params parsing for routes with multiple paths and multiple params (#1621)

* fix required params parsing for routes with multiple paths and multiple params

* fix incorrect variable declaration of validParams

* parser: if all tags negate return true on no hits (#1624)

* parser: if all tags negate return true on no hits

* fix: enums in body got parse incorrectly (#1625)

* parse binary literal const (#1593)

* support binary const

Signed-off-by: sdghchj <[email protected]>

* add test

Signed-off-by: sdghchj <[email protected]>

---------

Signed-off-by: sdghchj <[email protected]>

* feat: global security (#1620)

* global security

* improve test

* add cli flag --pdl to determine whether parse operations in dependency (#1605)

* change cli flag to parse operations in dependency

Signed-off-by: sdghchj <[email protected]>

* change cli flag to parse operations in dependency

Signed-off-by: sdghchj <[email protected]>

* add cli flag --pdl to determine whether parse operations in dependency

Signed-off-by: sdghchj <[email protected]>

* add cli flag --pdl to determine whether parse operations in dependency

Signed-off-by: sdghchj <[email protected]>

* add cli flag --pdl to determine whether parse operations in dependency

Signed-off-by: sdghchj <[email protected]>

---------

Signed-off-by: sdghchj <[email protected]>

* feat: add --packagePrefix=P for only parse packages matched by prefix P (#1582)

* enchancement: report which property is triggering a parsing error (#1439)

* add byte check before and after file is formatted (#1637)

* feat: preserve file permission when write formatted files (#1636)

test: add a test case to validate permission equal

* docs(readme): fix param brace (#1647)

* chore(deps): bump gopkg.in/yaml.v3 (#1663)

Bumps gopkg.in/yaml.v3 from 3.0.0-20200615113413-eeeca48fe776 to 3.0.0.

---
updated-dependencies:
- dependency-name: gopkg.in/yaml.v3
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* yaml.v3 security patch (#1664)

* test: remove redundant `filepath.Clean` call (#1675)

* chore(deps): bump golang.org/x/net from 0.8.0 to 0.17.0 (#1686)

Bumps [golang.org/x/net](https://github.com/golang/net) from 0.8.0 to 0.17.0.
- [Commits](golang/net@v0.8.0...v0.17.0)

---
updated-dependencies:
- dependency-name: golang.org/x/net
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* chore(deps): bump golang.org/x/net in /example/markdown (#1685)

Bumps [golang.org/x/net](https://github.com/golang/net) from 0.7.0 to 0.17.0.
- [Commits](golang/net@v0.7.0...v0.17.0)

---
updated-dependencies:
- dependency-name: golang.org/x/net
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* When the return value defined by the @success tag is equal to a null value, make fixes to prevent a null pointer exception occurs (#1667)

* chore(deps): bump golang.org/x/net in /example/go-module-support (#1682)

Bumps [golang.org/x/net](https://github.com/golang/net) from 0.10.0 to 0.17.0.
- [Commits](golang/net@v0.10.0...v0.17.0)

---
updated-dependencies:
- dependency-name: golang.org/x/net
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* chore(deps): bump golang.org/x/net in /example/object-map-example (#1684)

Bumps [golang.org/x/net](https://github.com/golang/net) from 0.10.0 to 0.17.0.
- [Commits](golang/net@v0.10.0...v0.17.0)

---
updated-dependencies:
- dependency-name: golang.org/x/net
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* chore(deps): bump golang.org/x/net in /example/celler (#1683)

Bumps [golang.org/x/net](https://github.com/golang/net) from 0.10.0 to 0.17.0.
- [Commits](golang/net@v0.10.0...v0.17.0)

---
updated-dependencies:
- dependency-name: golang.org/x/net
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* docs: add PT and EN examples for Go generic types (#1697)

* Update README.md (#1698)

Adding instructions to finish the steps in `Getting started` section before `How to use it with Gin`
It is easy for anybody to miss out that section which causes unwanted failures in the Swagger UI

* update gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776 to 3.0.0 (#1640)

* improve docker container usage (#1704)

* Update Go build version for Docker container

* Explicitly specify copy target

* Set ENTRYPOINT

* Move binary to /bin

* Add docker usage instructions to the README

* Set /code as the default WORKDIR

---------

Co-authored-by: Norman Gehrsitz <[email protected]>

* fix issue #1662: find definitions from external packages first (#1666)

Signed-off-by: sdghchj <[email protected]>

* Drop support for go v1.17.x (#1723)

* Drop support for go v1.17.x 

Signed-off-by: sdghchj <[email protected]>

* Add flag state #1628 (#1629)

* add state flag

* fix deps (#1724)

Signed-off-by: sdghchj <[email protected]>

* chore(deps): bump golang.org/x/crypto in /example/celler (#1727)

Bumps [golang.org/x/crypto](https://github.com/golang/crypto) from 0.14.0 to 0.17.0.
- [Commits](golang/crypto@v0.14.0...v0.17.0)

---
updated-dependencies:
- dependency-name: golang.org/x/crypto
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* chore(deps): bump golang.org/x/crypto in /example/go-module-support (#1726)

Bumps [golang.org/x/crypto](https://github.com/golang/crypto) from 0.14.0 to 0.17.0.
- [Commits](golang/crypto@v0.14.0...v0.17.0)

---
updated-dependencies:
- dependency-name: golang.org/x/crypto
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* chore(deps): bump golang.org/x/crypto in /example/object-map-example (#1725)

Bumps [golang.org/x/crypto](https://github.com/golang/crypto) from 0.14.0 to 0.17.0.
- [Commits](golang/crypto@v0.14.0...v0.17.0)

---
updated-dependencies:
- dependency-name: golang.org/x/crypto
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* deprecate some parts of routers in an operation (#1735)

Signed-off-by: sdghchj <[email protected]>

* bug: array form filed name should not contains bracket which led to invalid fieldname in ts codegen (#1706)

* Struct fields supported for header and path param types (#1740)

* Support object data types for header params

Add initial struct test for header names and validation.

* Add form and query struct test for operations

* Operation param add path struct model support and tests

wip: fix merge

* fix #1742 (#1744)

* fix #1742

Signed-off-by: sdghchj <[email protected]>

* Feat: Support generic with map params (#1746)

* support generic with map params

Signed-off-by: sdghchj <[email protected]>

* Update version.go (#1751)

* Update operation.go (#1753)

getUnderlyingSchema can return nil, so it has to be checked here otherwise the code is exposed to invalid memory address or nil pointer dereference

* fix: remove dropped tags from general infos (#1764)

* fix: remove unneeded tags from general infos
Signed-off-by: sdghchj <[email protected]>

* Update docker go build version to 1.21 (#1758)

* add support for "title" tag (#1762)

feat: add support for "title" tag in structField struct to allow specifying a custom field title

* chore: fix some typos in comments (#1788)

Signed-off-by: camcui <[email protected]>

* bump go version (#1797)

* bump go version
* cleanup pipeline

* chore(deps): bump golang.org/x/net from 0.17.0 to 0.23.0 (#1793)

Bumps [golang.org/x/net](https://github.com/golang/net) from 0.17.0 to 0.23.0.
- [Commits](golang/net@v0.17.0...v0.23.0)

---
updated-dependencies:
- dependency-name: golang.org/x/net
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* chore(deps): bump golang.org/x/net in /example/markdown (#1792)

Bumps [golang.org/x/net](https://github.com/golang/net) from 0.17.0 to 0.23.0.
- [Commits](golang/net@v0.17.0...v0.23.0)

---
updated-dependencies:
- dependency-name: golang.org/x/net
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* chore(deps): bump golang.org/x/net in /example/celler (#1794)

Bumps [golang.org/x/net](https://github.com/golang/net) from 0.17.0 to 0.23.0.
- [Commits](golang/net@v0.17.0...v0.23.0)

---
updated-dependencies:
- dependency-name: golang.org/x/net
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* chore(deps): bump golang.org/x/net in /example/go-module-support (#1795)

Bumps [golang.org/x/net](https://github.com/golang/net) from 0.17.0 to 0.23.0.
- [Commits](golang/net@v0.17.0...v0.23.0)

---
updated-dependencies:
- dependency-name: golang.org/x/net
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* chore(deps): bump golang.org/x/net in /example/object-map-example (#1796)

Bumps [golang.org/x/net](https://github.com/golang/net) from 0.17.0 to 0.23.0.
- [Commits](golang/net@v0.17.0...v0.23.0)

---
updated-dependencies:
- dependency-name: golang.org/x/net
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* Handle case of empty GOROOT (#1798)

In some situations, such as when using the go-swag Nix package, runtime.GOROOT() will be empty, and RangeFiles will skip all source paths since technically, all paths are prefixed with the empty string.

See also NixOS/nixpkgs#224701

May resolve some cases of #1622.

* Added multiline support for @description attribute for securityDefinitions (#1786)

* Feat: multi-arch docker image (#1756)

* Feat: multi-arch docker image

- adapt Dockerfile to support cross-compilation depending on TARGETARCH and TARGETOS variables see https://www.docker.com/blog/faster-multi-platform-builds-dockerfile-cross-compilation-guide/
- set target platforms for docker/build-push-action

* Support running on forks

* Fix ARG format

* Fix docker digest step

* Restrict permissions

* Update action versions

* Set $TARGETPLATFORM explicitly

docker/build-push-action#820 (comment)

---------

Co-authored-by: Norman Gehrsitz <[email protected]>

* chore(deps): bump google.golang.org/protobuf (#1773)

Bumps google.golang.org/protobuf from 1.30.0 to 1.33.0.

---
updated-dependencies:
- dependency-name: google.golang.org/protobuf
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* chore(deps): bump google.golang.org/protobuf (#1774)

Bumps google.golang.org/protobuf from 1.30.0 to 1.33.0.

---
updated-dependencies:
- dependency-name: google.golang.org/protobuf
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* chore(deps): bump google.golang.org/protobuf in /example/celler (#1775)

Bumps google.golang.org/protobuf from 1.30.0 to 1.33.0.

---
updated-dependencies:
- dependency-name: google.golang.org/protobuf
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* fix issue: #1780: filter $GOROOT path (#1827)

Signed-off-by: song <[email protected]>

* feat: read from stdin, write to stdout (#1831) (#1832)

Co-authored-by: Bruno Bonatto <[email protected]>

* Added suport for parsing comments inside of function bodies (#1824)

Added suport for parsing comments inside of function bodies

---------

Co-authored-by: Jonas Ha <[email protected]>

* adds support for complex types with function scope (#1813)

* [Issue 1812] fix misalignment in expected.json and api.go messing with parser_test (#1836)

* Fixes Issue 1829 (#1830)

* fix: fixes a bug that could select wrong tag description markdown file

* fixes parser to be able to parse file names with and without ext

* Fix global overrides for any/interface ref types (#1835)

When overriding with any or interface{}, the code should prefer the "any" (empty) schema instead, not the object schema since that's different e.g.

* adds support for pointer function scoped fields (#1841)

* fix parse nested structs and aliases (#1866)

Co-authored-by: ma.mikhaylov <[email protected]>

* Fix generics used with function scoped types (#1883)

* Fix param comment escaping issue (#1890)

This commit fixes a param comment issue where a "\n" gets escaped so it would not be applied to the output swagger file.

* support markdown description for declaration (#1893)

* feat: support markdown description for declaration

* fix: range PackagesDefinitions.uniqueDefinitions cause panic

---------

Co-authored-by: xinbi.nie <[email protected]>

* update README (#1856)

* Update docs for request and response headers (#1825)

* fix:parse all field names declared in a row (#1872)

* fix:parse all fields names declared in a row

* Flags to parse internal and dependency package (#1894)

* fix: failing assert in enums test on 32bit (#1634)

* Feat: Add support for parenthesis in router patterns (#1859)

* chore: Update ci.yml (#1902)

* new release (#1901)

* fix some issues

* fix unit tests

---------

Signed-off-by: sdghchj <[email protected]>
Signed-off-by: dependabot[bot] <[email protected]>
Signed-off-by: camcui <[email protected]>
Signed-off-by: song <[email protected]>
Co-authored-by: tzxdtc10 <[email protected]>
Co-authored-by: Leo Palmer Sunmo <[email protected]>
Co-authored-by: sdghchj <[email protected]>
Co-authored-by: Nerzal <[email protected]>
Co-authored-by: Tobias Theel <[email protected]>
Co-authored-by: Paulo Lopes Estevão <[email protected]>
Co-authored-by: lowang-bh <[email protected]>
Co-authored-by: wanglonghui7 <[email protected]>
Co-authored-by: Martin W. Kirst <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Phenix66 <[email protected]>
Co-authored-by: Roy Marples <[email protected]>
Co-authored-by: Billy Ho <[email protected]>
Co-authored-by: nameoffnv <[email protected]>
Co-authored-by: Shengyu Zhang <[email protected]>
Co-authored-by: Sakis <[email protected]>
Co-authored-by: Daniel Moncada <[email protected]>
Co-authored-by: wholesome-ghoul <[email protected]>
Co-authored-by: Shimizu1111 <[email protected]>
Co-authored-by: Renan Silva <[email protected]>
Co-authored-by: Saurabh Chatterjee <[email protected]>
Co-authored-by: caption <[email protected]>
Co-authored-by: ngehrsitz <[email protected]>
Co-authored-by: Norman Gehrsitz <[email protected]>
Co-authored-by: Ivan Volkov <[email protected]>
Co-authored-by: Jinof <[email protected]>
Co-authored-by: Joe Shaw <[email protected]>
Co-authored-by: Mathieu Chauvet <[email protected]>
Co-authored-by: Matteo Bassan <[email protected]>
Co-authored-by: camcui <[email protected]>
Co-authored-by: Evan Goode <[email protected]>
Co-authored-by: Vladimir Avchenov <[email protected]>
Co-authored-by: Timo Naroska <[email protected]>
Co-authored-by: bob <[email protected]>
Co-authored-by: bfbonatto <[email protected]>
Co-authored-by: Bruno Bonatto <[email protected]>
Co-authored-by: j-d-ha <[email protected]>
Co-authored-by: Jonas Ha <[email protected]>
Co-authored-by: Kristoffer Fage Jensen <[email protected]>
Co-authored-by: Michi H <[email protected]>
Co-authored-by: Ezequiel Rodriguez <[email protected]>
Co-authored-by: zdon0 <[email protected]>
Co-authored-by: ma.mikhaylov <[email protected]>
Co-authored-by: Berk Karaal <[email protected]>
Co-authored-by: Yuki Omoto <[email protected]>
Co-authored-by: nicoxix <[email protected]>
Co-authored-by: xinbi.nie <[email protected]>
Co-authored-by: Eike Haller <[email protected]>
Co-authored-by: Harsh Mittal <[email protected]>
Co-authored-by: Leso_KN <[email protected]>
Co-authored-by: alifemove <[email protected]>
  • Loading branch information
Show file tree
Hide file tree
Showing 68 changed files with 4,141 additions and 721 deletions.
5 changes: 2 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ jobs:
test:
strategy:
matrix:
go: [ '1.18.x', '1.19.x', '1.20.x' ]
go: [ '1.19.x', '1.20.x', '1.21.x', '1.22.x' ]
platform: [ubuntu-latest, macos-latest]
runs-on: ${{ matrix.platform }}
steps:
Expand All @@ -22,8 +22,7 @@ jobs:
- name: deps
run: make deps
- name: static program analysis
run: |
make fmt-check lint vet
run: make fmt-check vet
- name: build
run: make build
- name: test
Expand Down
20 changes: 13 additions & 7 deletions .github/workflows/docker.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,38 +5,44 @@ on:
tags:
- 'v*'

permissions:
contents: read
packages: write

jobs:
docker-build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
uses: actions/checkout@v4

- name: Set up Docker Buildx
id: buildx
uses: docker/setup-buildx-action@v2
uses: docker/setup-buildx-action@v3

- name: Login to Github Packages
uses: docker/login-action@v2
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}

- name: Docker meta
id: meta
uses: docker/metadata-action@v4
uses: docker/metadata-action@v5
with:
images: ghcr.io/swaggo/swag

- name: Build image and push to GitHub Container Registry
uses: docker/build-push-action@v2
id: docker_build
uses: docker/build-push-action@v5
with:
context: .
platforms: linux/amd64,linux/arm64
push: true
tags: |
ghcr.io/swaggo/swag:latest
ghcr.io/swaggo/swag:${{github.ref_name}}
ghcr.io/${{ github.repository }}:latest
ghcr.io/${{ github.repository }}:${{github.ref_name}}
labels: ${{ steps.meta.outputs.labels }}

- name: Image digest
Expand Down
16 changes: 12 additions & 4 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Dockerfile References: https://docs.docker.com/engine/reference/builder/

# Start from the latest golang base image
FROM golang:1.18.3-alpine as builder
FROM --platform=$BUILDPLATFORM golang:1.21-alpine as builder

# Set the Current Working Directory inside the container
WORKDIR /app
Expand All @@ -15,14 +15,22 @@ RUN go mod download
# Copy the source from the current directory to the Working Directory inside the container
COPY . .

# Configure go compiler target platform
ARG TARGETOS
ARG TARGETARCH
ENV GOARCH=$TARGETARCH \
GOOS=$TARGETOS

# Build the Go app
RUN CGO_ENABLED=0 GOOS=linux go build -v -a -installsuffix cgo -o swag cmd/swag/main.go


######## Start a new stage from scratch #######
FROM scratch
FROM --platform=$TARGETPLATFORM scratch

WORKDIR /root/
WORKDIR /code/

# Copy the Pre-built binary file from the previous stage
COPY --from=builder /app/swag .
COPY --from=builder /app/swag /bin/swag

ENTRYPOINT ["/bin/swag"]
22 changes: 3 additions & 19 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ GOBUILD:=$(GOCMD) build
GOINSTALL:=$(GOCMD) install
GOCLEAN:=$(GOCMD) clean
GOTEST:=$(GOCMD) test
GOMODTIDY:=$(GOCMD) mod tidy
GOGET:=$(GOCMD) get
GOLIST:=$(GOCMD) list
GOVET:=$(GOCMD) vet
Expand All @@ -16,8 +17,6 @@ BINARY_NAME:=swag
PACKAGES:=$(shell $(GOLIST) github.com/swaggo/swag/v2 github.com/swaggo/swag/v2/cmd/swag github.com/swaggo/swag/v2/gen github.com/swaggo/swag/v2/format)
GOFILES:=$(shell find . -name "*.go" -type f)

export GO111MODULE := on

all: test build

.PHONY: build
Expand Down Expand Up @@ -54,25 +53,10 @@ clean:

.PHONY: deps
deps:
$(GOGET) github.com/swaggo/cli
$(GOGET) sigs.k8s.io/yaml
$(GOGET) github.com/KyleBanks/depth
$(GOGET) github.com/go-openapi/jsonreference
$(GOGET) github.com/go-openapi/spec
$(GOGET) github.com/stretchr/testify/assert
$(GOGET) golang.org/x/tools/go/loader

.PHONY: devel-deps
devel-deps:
GO111MODULE=off $(GOGET) -v -u \
golang.org/x/lint/golint

.PHONY: lint
lint: devel-deps
for PKG in $(PACKAGES); do golint -set_exit_status $$PKG || exit 1; done;
$(GOMODTIDY)

.PHONY: vet
vet: deps devel-deps
vet: deps
$(GOVET) $(PACKAGES)

.PHONY: fmt
Expand Down
93 changes: 70 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,8 @@ Swag converts Go annotations to Swagger Documentation 2.0. We've created a varie
- [User defined structure with an array type](#user-defined-structure-with-an-array-type)
- [Function scoped struct declaration](#function-scoped-struct-declaration)
- [Model composition in response](#model-composition-in-response)
- [Add a headers in response](#add-a-headers-in-response)
- [Add headers in request](#add-request-headers)
- [Add headers in response](#add-a-headers-in-response)
- [Use multiple path params](#use-multiple-path-params)
- [Add multiple paths](#add-multiple-paths)
- [Example value of struct](#example-value-of-struct)
Expand All @@ -56,6 +57,7 @@ Swag converts Go annotations to Swagger Documentation 2.0. We've created a varie
- [How to use security annotations](#how-to-use-security-annotations)
- [Add a description for enum items](#add-a-description-for-enum-items)
- [Generate only specific docs file types](#generate-only-specific-docs-file-types)
- [How to use Go generic types](#how-to-use-generics)
- [Change the default Go Template action delimiters](#change-the-default-go-template-action-delimiters)
- [About the Project](#about-the-project)
- [Contributors](#contributors)
Expand All @@ -67,11 +69,16 @@ Swag converts Go annotations to Swagger Documentation 2.0. We've created a varie

1. Add comments to your API source code, See [Declarative Comments Format](#declarative-comments-format).

2. Download swag by using:
2. Install swag by using:
```sh
go install github.com/swaggo/swag/v2/cmd/swag@latest
```
To build from source you need [Go](https://golang.org/dl/) (1.18 or newer).
To build from source you need [Go](https://golang.org/dl/) (1.19 or newer).

Alternatively you can run the docker image:
```sh
docker run --rm -v $(pwd):/code ghcr.io/swaggo/swag:latest
```

Or download a pre-compiled binary from the [release page](https://github.com/swaggo/swag/releases).

Expand All @@ -81,6 +88,9 @@ swag init
```

Make sure to import the generated `docs/docs.go` so that your specific configuration gets `init`'ed. If your General API annotations do not live in `main.go`, you can let swag know with `-g` flag.
```go
import _ "example-module-name/docs"
```
```sh
swag init -g http/api.go
```
Expand Down Expand Up @@ -112,6 +122,7 @@ OPTIONS:
--outputTypes value, --ot value Output types of generated files (docs.go, swagger.json, swagger.yaml) like go,json,yaml (default: "go,json,yaml")
--parseVendor Parse go files in 'vendor' folder, disabled by default (default: false)
--parseDependency, --pd Parse go files inside dependency folder, disabled by default (default: false)
--parseDependencyLevel, --pdl Enhancement of '--parseDependency', parse go files inside dependency folder, 0 disabled, 1 only parse models, 2 only parse operations, 3 parse all (default: 0)
--markdownFiles value, --md value Parse folder containing markdown files to use as description, disabled by default
--codeExampleFiles value, --cef value Parse folder containing code example files to use for the x-codeSamples extension, disabled by default
--parseInternal Parse go files in internal packages, disabled by default (default: false)
Expand All @@ -125,6 +136,9 @@ OPTIONS:
--tags value, -t value A comma-separated list of tags to filter the APIs for which the documentation is generated.Special case if the tag is prefixed with the '!' character then the APIs with that tag will be excluded
--v3.1 Generate OpenAPI V3.1 spec (default: false)
--templateDelims value, --td value Provide custom delimeters for Go template generation. The format is leftDelim,rightDelim. For example: "[[,]]"
--collectionFormat value, --cf value Set default collection format (default: "csv")
--state value Initial state for the state machine (default: ""), @HostState in root file, @State in other files
--parseFuncBody Parse API info within body of functions in go files, disabled by default (default: false)
--packageName --output A package name of docs.go, using output directory name by default (check --output option)
--collectionFormat value, --cf value Set default collection format (default: "csv")
--help, -h show help
Expand Down Expand Up @@ -163,6 +177,7 @@ OPTIONS:

Find the example source code [here](https://github.com/swaggo/swag/tree/master/example/celler).

Finish the steps in [Getting started](#getting-started)
1. After using `swag init` to generate Swagger 2.0 docs, import the following packages:
```go
import "github.com/swaggo/gin-swagger" // gin-swagger middleware
Expand Down Expand Up @@ -443,25 +458,26 @@ The following annotations are only available if you set the -v3.1 flag in the CL
[celler/controller](https://github.com/swaggo/swag/tree/master/example/celler/controller)


| annotation | description |
|-------------|----------------------------------------------------------------------------------------------------------------------------|
| description | A verbose explanation of the operation behavior. |
| description.markdown | A short description of the application. The description will be read from a file. E.g. `@description.markdown details` will load `details.md`| // @description.file endpoint.description.markdown |
| id | A unique string used to identify the operation. Must be unique among all API operations. |
| tags | A list of tags to each API operation that separated by commas. |
| summary | A short summary of what the operation does. |
| accept | A list of MIME types the APIs can consume. Note that Accept only affects operations with a request body, such as POST, PUT and PATCH. Value MUST be as described under [Mime Types](#mime-types). |
| produce | A list of MIME types the APIs can produce. Value MUST be as described under [Mime Types](#mime-types). |
| param | Parameters that separated by spaces. `param name`,`param type`,`data type`,`is mandatory?`,`comment` `attribute(optional)` |
| security | [Security](#security) to each API operation. |
| success | Success response that separated by spaces. `return code or default`,`{param type}`,`data type`,`comment` |
| failure | Failure response that separated by spaces. `return code or default`,`{param type}`,`data type`,`comment` |
| response | As same as `success` and `failure` |
| header | Header in response that separated by spaces. `return code`,`{param type}`,`data type`,`comment` |
| router | Path definition that separated by spaces. `path`,`[httpMethod]` |
| x-name | The extension key, must be start by x- and take only json value. |
| x-codeSample | Optional Markdown usage. take `file` as parameter. This will then search for a file named like the summary in the given folder. |
| deprecated | Mark endpoint as deprecated. |
| annotation | description |
|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| description | A verbose explanation of the operation behavior. |
| description.markdown | A short description of the application. The description will be read from a file. E.g. `@description.markdown details` will load `details.md` | // @description.file endpoint.description.markdown |
| id | A unique string used to identify the operation. Must be unique among all API operations. |
| tags | A list of tags to each API operation that separated by commas. |
| summary | A short summary of what the operation does. |
| accept | A list of MIME types the APIs can consume. Note that Accept only affects operations with a request body, such as POST, PUT and PATCH. Value MUST be as described under [Mime Types](#mime-types). |
| produce | A list of MIME types the APIs can produce. Value MUST be as described under [Mime Types](#mime-types). |
| param | Parameters that separated by spaces. `param name`,`param type`,`data type`,`is mandatory?`,`comment` `attribute(optional)` |
| security | [Security](#security) to each API operation. |
| success | Success response that separated by spaces. `return code or default`,`{param type}`,`data type`,`comment` |
| failure | Failure response that separated by spaces. `return code or default`,`{param type}`,`data type`,`comment` |
| response | As same as `success` and `failure` |
| header | Header in response that separated by spaces. `return code`,`{param type}`,`data type`,`comment` |
| router | Path definition that separated by spaces. `path`,`[httpMethod]` |
| deprecatedrouter | As same as router, but deprecated. |
| x-name | The extension key, must be start by x- and take only json value. |
| x-codeSample | Optional Markdown usage. take `file` as parameter. This will then search for a file named like the summary in the given folder. |
| deprecated | Mark endpoint as deprecated. |



Expand Down Expand Up @@ -663,7 +679,14 @@ type DeepObject struct { //in `proto` package
}
@success 200 {object} jsonresult.JSONResult{data1=proto.Order{data=proto.DeepObject},data2=[]proto.Order{data=[]proto.DeepObject}} "desc"
```
### Add a headers in response
### Add response request

```go
// @Param X-MyHeader header string true "MyHeader must be set for valid response"
// @Param X-API-VERSION header string true "API version eg.: 1.0"
```

### Add response headers

```go
// @Success 200 {string} string "ok"
Expand Down Expand Up @@ -939,6 +962,19 @@ By default `swag` command generates Swagger specification in three different fil

If you would like to limit a set of file types which should be generated you can use `--outputTypes` (short `-ot`) flag. Default value is `go,json,yaml` - output types separated with comma. To limit output only to `go` and `yaml` files, you would write `go,yaml`. With complete command that would be `swag init --outputTypes go,yaml`.

### How to use Generics

```go
// @Success 200 {object} web.GenericNestedResponse[types.Post]
// @Success 204 {object} web.GenericNestedResponse[types.Post, Types.AnotherOne]
// @Success 201 {object} web.GenericNestedResponse[web.GenericInnerType[types.Post]]
func GetPosts(w http.ResponseWriter, r *http.Request) {
_ = web.GenericNestedResponse[types.Post]{}
}
```
See [this file](https://github.com/swaggo/swag/blob/master/testdata/generics_nested/api/api.go) for more details
and other examples.

### Change the default Go Template action delimiters
[#980](https://github.com/swaggo/swag/issues/980)
[#1177](https://github.com/swaggo/swag/issues/1177)
Expand All @@ -951,6 +987,17 @@ swag init -g http/api.go -td "[[,]]"
```
The new delimiter is a string with the format "`<left delimiter>`,`<right delimiter>`".

### Parse Internal and Dependency Packages

If the struct is defined in a dependency package, use `--parseDependency`.

If the struct is defined in your main project, use `--parseInternal`.

if you want to include both internal and from dependencies use both flags
```
swag init --parseDependency --parseInternal
```

## About the Project
This project was inspired by [yvasiyarov/swagger](https://github.com/yvasiyarov/swagger) but we simplified the usage and added support a variety of [web frameworks](#supported-web-frameworks). Gopher image source is [tenntenn/gopher-stickers](https://github.com/tenntenn/gopher-stickers). It has licenses [creative commons licensing](http://creativecommons.org/licenses/by/3.0/deed.en).
## Contributors
Expand Down
Loading

0 comments on commit 7b50e07

Please sign in to comment.