[teamai] Push 87 resource(s) from XingfenD

2026-09-10 16:10:45 +08:00
parent 425c9c078a
commit 65c04def51
1314 changed files with 211681 additions and 0 deletions
@@ -0,0 +1,120 @@
+# swag CLI Reference
+
+## swag init — Generate Documentation
+
+```bash
+swag init                                      # parse main.go, generate docs/
+swag init -g cmd/api/main.go                   # general info in a different file
+swag init -d ./handlers,./models               # additional directories to parse
+swag init --exclude ./vendor,./internal/gen    # skip directories
+swag init -ot go,json                          # output only Go and JSON (skip YAML)
+swag init -q                                   # quiet mode (no log output)
+swag init --parseInternal                      # include internal/ packages
+swag init --parseDependency                    # parse vendor/module dependencies
+swag init --requiredByDefault                  # mark all struct fields as required
+swag init -p camelcase                         # property naming: snakecase | camelcase | pascalcase
+swag init --tags Users,Products                # only generate for these tags
+swag init --tags '!Internal'                   # exclude tag (! prefix)
+swag init --td "[[,]]"                         # custom template delimiters
+```
+
+## swag fmt — Format Annotations
+
+```bash
+swag fmt                                       # format all annotation comments
+swag fmt -d ./handlers                         # format specific directory
+swag fmt --exclude ./vendor                    # skip directories
+```
+
+`swag fmt` requires a standard Go doc comment (`// FuncName godoc`) immediately before the first `@` annotation — without it the formatter cannot determine indentation.
+
+## Framework Integration Packages
+
+| Framework                | Package                             |
+| ------------------------ | ----------------------------------- |
+| Gin                      | `github.com/swaggo/gin-swagger`     |
+| Echo                     | `github.com/swaggo/echo-swagger`    |
+| Fiber                    | `github.com/swaggo/fiber-swagger`   |
+| Chi / net/http / Gorilla | `github.com/swaggo/http-swagger`    |
+| Buffalo                  | `github.com/swaggo/buffalo-swagger` |
+| Hertz                    | `github.com/hertz-contrib/swagger`  |
+
+The shared files package (`github.com/swaggo/files`) is required by all integrations.
+
+## Dynamic Configuration
+
+Override spec values at runtime — useful for multi-environment deployments where host and basepath differ between staging and production:
+
+```go
+import docs "yourmodule/docs"  // named import required to access docs.SwaggerInfo
+
+func main() {
+    docs.SwaggerInfo.Title       = "My API"
+    docs.SwaggerInfo.Description = "Production API"
+    docs.SwaggerInfo.Version     = "2.0"
+    docs.SwaggerInfo.Host        = os.Getenv("API_HOST")
+    docs.SwaggerInfo.BasePath    = "/api/v1"
+    docs.SwaggerInfo.Schemes     = []string{"https"}
+}
+```
+
+## Generics (swag v2)
+
+Single type parameter:
+
+```go
+// @Success 200 {object} api.Response[model.User]
+// @Success 200 {array}  api.Response[model.User]
+```
+
+Multiple type parameters:
+
+```go
+// @Success 200 {object} api.Response[model.User, model.Meta]
+```
+
+## Nested Composition
+
+Embed or override fields in the documented schema without changing Go types:
+
+```go
+// @Success 200 {object} api.Envelope{data=model.User}
+// @Success 200 {object} api.Envelope{data=[]model.User}
+// @Success 200 {object} api.Envelope{data=model.User,meta=api.Pagination}
+```
+
+## Response Headers
+
+```go
+// @Header 200       {string} X-Request-ID "Unique request identifier"
+// @Header 200,400   {string} X-Request-ID "Unique request identifier"
+// @Header all       {string} X-Request-ID "Present on every response"
+```
+
+## Function-Scoped Structs
+
+swag can parse structs defined inside handler functions:
+
+```go
+// @Param req body main.CreateUser.request true "Create user input"
+func CreateUser(c *gin.Context) {
+    type request struct {
+        Name  string `json:"name"`
+        Email string `json:"email"`
+    }
+}
+```
+
+## MIME Type Aliases
+
+| Alias                   | Content-Type                      |
+| ----------------------- | --------------------------------- |
+| `json`                  | application/json                  |
+| `xml`                   | application/xml                   |
+| `plain`                 | text/plain                        |
+| `html`                  | text/html                         |
+| `mpfd`                  | multipart/form-data               |
+| `x-www-form-urlencoded` | application/x-www-form-urlencoded |
+| `octet-stream`          | application/octet-stream          |
+| `png` / `jpeg` / `gif`  | image/png, image/jpeg, image/gif  |
+| `event-stream`          | text/event-stream                 |