You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[Example value of struct](#example-value-of-struct)
@@ -57,7 +56,6 @@ Swag converts Go annotations to Swagger Documentation 2.0. We've created a varie
57
56
-[How to use security annotations](#how-to-use-security-annotations)
58
57
-[Add a description for enum items](#add-a-description-for-enum-items)
59
58
-[Generate only specific docs file types](#generate-only-specific-docs-file-types)
60
-
-[How to use Go generic types](#how-to-use-generics)
61
59
-[Change the default Go Template action delimiters](#change-the-default-go-template-action-delimiters)
62
60
-[About the Project](#about-the-project)
63
61
-[Contributors](#contributors)
@@ -69,16 +67,11 @@ Swag converts Go annotations to Swagger Documentation 2.0. We've created a varie
69
67
70
68
1. Add comments to your API source code, See [Declarative Comments Format](#declarative-comments-format).
71
69
72
-
2.Install swag by using:
70
+
2.Download swag by using:
73
71
```sh
74
72
go install github.com/swaggo/swag/v2/cmd/swag@latest
75
73
```
76
-
To build from source you need [Go](https://golang.org/dl/) (1.19 or newer).
77
-
78
-
Alternatively you can run the docker image:
79
-
```sh
80
-
docker run --rm -v $(pwd):/code ghcr.io/swaggo/swag:latest
81
-
```
74
+
To build from source you need [Go](https://golang.org/dl/) (1.18 or newer).
82
75
83
76
Or download a pre-compiled binary from the [release page](https://github.com/swaggo/swag/releases).
84
77
@@ -88,9 +81,6 @@ swag init
88
81
```
89
82
90
83
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.
91
-
```go
92
-
import _ "example-module-name/docs"
93
-
```
94
84
```sh
95
85
swag init -g http/api.go
96
86
```
@@ -122,7 +112,6 @@ OPTIONS:
122
112
--outputTypes value, --ot value Output types of generated files (docs.go, swagger.json, swagger.yaml) like go,json,yaml (default: "go,json,yaml")
123
113
--parseVendor Parse go files in'vendor' folder, disabled by default (default: false)
124
114
--parseDependency, --pd Parse go files inside dependency folder, disabled by default (default: false)
125
-
--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)
126
115
--markdownFiles value, --md value Parse folder containing markdown files to use as description, disabled by default
127
116
--codeExampleFiles value, --cef value Parse folder containing code example files to use for the x-codeSamples extension, disabled by default
128
117
--parseInternal Parse go files in internal packages, disabled by default (default: false)
@@ -136,9 +125,6 @@ OPTIONS:
136
125
--tags value, -t value A comma-separated list of tags to filter the APIs for which the documentation is generated.Special caseif the tag is prefixed with the '!' character then the APIs with that tag will be excluded
| description | A verbose explanation of the operation behavior. |
464
-
| 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 |
465
-
| id | A unique string used to identify the operation. Must be unique among all API operations. |
466
-
| tags | A list of tags to each API operation that separated by commas. |
467
-
| summary | A short summary of what the operation does. |
468
-
| 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). |
469
-
| produce | A list of MIME types the APIs can produce. Value MUST be as described under [Mime Types](#mime-types). |
470
-
| param | Parameters that separated by spaces. `param name`,`param type`,`data type`,`is mandatory?`,`comment``attribute(optional)`|
471
-
| security | [Security](#security) to each API operation. |
472
-
| success | Success response that separated by spaces. `return code or default`,`{param type}`,`data type`,`comment`|
473
-
| failure | Failure response that separated by spaces. `return code or default`,`{param type}`,`data type`,`comment`|
474
-
| response | As same as `success` and `failure`|
475
-
| header | Header in response that separated by spaces. `return code`,`{param type}`,`data type`,`comment`|
476
-
| router | Path definition that separated by spaces. `path`,`[httpMethod]`|
477
-
| deprecatedrouter | As same as router, but deprecated. |
478
-
| x-name | The extension key, must be start by x- and take only json value. |
479
-
| x-codeSample | Optional Markdown usage. take `file` as parameter. This will then search fora file named like the summaryin the given folder. |
| description | A verbose explanation of the operation behavior. |
449
+
| 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 |
450
+
| id | A unique string used to identify the operation. Must be unique among all API operations. |
451
+
| tags | A list of tags to each API operation that separated by commas. |
452
+
| summary | A short summary of what the operation does. |
453
+
| 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). |
454
+
| produce | A list of MIME types the APIs can produce. Value MUST be as described under [Mime Types](#mime-types). |
455
+
| param | Parameters that separated by spaces. `param name`,`param type`,`data type`,`is mandatory?`,`comment``attribute(optional)`|
456
+
| security | [Security](#security) to each API operation. |
457
+
| success | Success response that separated by spaces. `return code or default`,`{param type}`,`data type`,`comment`|
458
+
| failure | Failure response that separated by spaces. `return code or default`,`{param type}`,`data type`,`comment`|
459
+
| response | As same as `success` and `failure`|
460
+
| header | Header in response that separated by spaces. `return code`,`{param type}`,`data type`,`comment`|
461
+
| router | Path definition that separated by spaces. `path`,`[httpMethod]`|
462
+
| x-name | The extension key, must be start by x- and take only json value. |
463
+
| x-codeSample | Optional Markdown usage. take `file` as parameter. This will then search fora file named like the summaryin the given folder. |
// @Param X-MyHeader header string true "MyHeader must be set for valid response"
686
-
// @Param X-API-VERSION header string true "API version eg.: 1.0"
687
-
```
688
-
689
-
### Add response headers
666
+
### Add a headers in response
690
667
691
668
```go
692
669
// @Success 200 {string} string "ok"
@@ -962,19 +939,6 @@ By default `swag` command generates Swagger specification in three different fil
962
939
963
940
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 completecommand that would be `swag init --outputTypes go,yaml`.
The new delimiter is a string with the format "`<left delimiter>`,`<right delimiter>`".
989
953
990
-
### Parse Internal and Dependency Packages
991
-
992
-
If the struct is defined in a dependency package, use `--parseDependency`.
993
-
994
-
If the struct is defined in your main project, use `--parseInternal`.
995
-
996
-
if you want to include both internal and from dependencies use both flags
997
-
```
998
-
swag init --parseDependency --parseInternal
999
-
```
1000
-
1001
954
## About the Project
1002
955
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).
0 commit comments