Merge pull request #1 from bodhisatan/main

feat: add swagger middleware

.gitignore

@@ -1 +1,17 @@
-.idea/
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+.idea

.licenserc.yaml

@@ -0,0 +1,38 @@
+header:
+  license:
+    spdx-id: Apache-2.0
+    copyright-owner: CloudWeGo Authors
+    content: |
+      MIT License
+      
+      Copyright (c) 2017 Swaggo
+      
+      Permission is hereby granted, free of charge, to any person obtaining a copy
+      of this software and associated documentation files (the "Software"), to deal
+      in the Software without restriction, including without limitation the rights
+      to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+      copies of the Software, and to permit persons to whom the Software is
+      furnished to do so, subject to the following conditions:
+      
+      The above copyright notice and this permission notice shall be included in all
+      copies or substantial portions of the Software.
+      
+      THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+      IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+      FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+      AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+      LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+      OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+      SOFTWARE.
+      
+      This file may have been modified by CloudWeGo authors. All CloudWeGo
+      Modifications are Copyright 2022 CloudWeGo Authors.
+
+  paths:
+    - '**/*.go'
+    - '**/*.s'
+
+  paths-ignore:
+    - '**/docs/**'
+
+  comment: on-failure

NOTICE

@@ -0,0 +1,5 @@
+CloudWeGo
+Copyright 2022 CloudWeGo authors.
+
+This product includes software developed at
+The Apache Software Foundation (http://www.apache.org/).

README.md

@@ -0,0 +1,169 @@
+# Hertz-swagger
+
+Hertz middleware to automatically generate RESTful API documentation with Swagger 2.0.
+
+## Usage
+
+### Start using it
+
+1. Add comments to your API source code, [See Declarative Comments Format](https://github.com/swaggo/swag/blob/master/README.md#declarative-comments-format).
+2. Download [Swag](https://github.com/swaggo/swag) for Go by using:
+
+```sh
+go get -u github.com/swaggo/swag/cmd/swag
+```
+
+Starting in Go 1.17, installing executables with `go get` is deprecated. `go install` may be used instead:
+
+```sh
+go install github.com/swaggo/swag/cmd/swag
+```
+
+3. Run the [Swag](https://github.com/swaggo/swag) at your Go project root path(for instance `~/root/go-peoject-name`),
+   [Swag](https://github.com/swaggo/swag) will parse comments and generate required files(`docs` folder and `docs/doc.go`)
+   at `~/root/go-peoject-name/docs`.
+
+```sh
+swag init
+```
+
+4. Download [hertz-swagger](https://github.com/hertz-contrib/swagger) by using:
+
+```sh
+go get -u github.com/hertz-contrib/swagger
+go get -u github.com/swaggo/files
+```
+
+Import following in your code:
+
+```go
+import "github.com/hertz-contrib/swagger" // hertz-swagger middleware
+import "github.com/swaggo/files" // swagger embed files
+
+```
+
+### Canonical example:
+
+Now assume you have implemented a simple api as following:
+
+```go
+func PingHandler(c context.Context, ctx *app.RequestContext) {
+    ctx.JSON(200, map[string]string{
+        "ping": "pong",
+    })
+}
+
+```
+
+So how to use hertz-swagger on api above? Just follow the following guide.
+
+1. Add Comments for apis and main function with hertz-swagger rules like following:
+
+```go
+// PingHandler 测试handler
+// @Summary 测试Summary
+// @Description 测试Description
+// @Accept application/json
+// @Produce application/json
+// @Router /ping [get]
+func PingHandler(c context.Context, ctx *app.RequestContext) {
+    ctx.JSON(200, map[string]string{
+        "ping": "pong",
+    })
+}
+```
+
+2. Use `swag init` command to generate a docs, docs generated will be stored at `docs/`.
+3. import the docs like this:
+   I assume your project named `github.com/go-project-name/docs`.
+
+```go
+import (
+   docs "github.com/go-project-name/docs"
+)
+```
+
+4. build your application and after that, go to http://localhost:8888/swagger/index.html ,you to see your Swagger UI.
+
+5. The full code and folder relatives here:
+
+```go
+package main
+
+import (
+	"context"
+	"github.com/cloudwego/hertz/pkg/app"
+	"github.com/cloudwego/hertz/pkg/app/server"
+	"github.com/hertz-contrib/swagger"
+	_ "github.com/hertz-contrib/swagger/example/basic/docs"
+	swaggerFiles "github.com/swaggo/files"
+)
+
+// PingHandler 测试handler
+// @Summary 测试Summary
+// @Description 测试Description
+// @Accept application/json
+// @Produce application/json
+// @Router /ping [get]
+func PingHandler(c context.Context, ctx *app.RequestContext) {
+	ctx.JSON(200, map[string]string{
+		"ping": "pong",
+	})
+}
+
+// @title HertzTest
+// @version 1.0
+// @description This is a demo using Hertz.
+
+// @contact.name hertz-contrib
+// @contact.url https://github.com/hertz-contrib
+
+// @license.name Apache 2.0
+// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
+
+// @host localhost:8888
+// @BasePath /
+// @schemes http
+func main() {
+	h := server.Default()
+
+	h.GET("/ping", PingHandler)
+
+	url := swagger.URL("http://localhost:8888/swagger/doc.json") // The url pointing to API definition
+	h.GET("/swagger/*any", swagger.WrapHandler(swaggerFiles.Handler, url))
+
+	h.Spin()
+}
+
+```
+
+Demo project tree, `swag init` is run at relative `.`
+
+```
+.
+├── docs
+│   ├── docs.go
+│   ├── swagger.json
+│   └── swagger.yaml
+├── go.mod
+├── go.sum
+└── main.go
+```
+
+## Multiple APIs
+This feature was introduced in swag v1.7.9
+
+## Configuration
+
+You can configure Swagger using different configuration options
+
+
+| Option                   | Type   | Default    | Description                                                                                                                                                                                                                                                 |
+| ------------------------ | ------ | ---------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| URL                      | string | "doc.json" | URL pointing to API definition                                                                                                                                                                                                                              |
+| DocExpansion             | string | "list"     | Controls the default expansion setting for the operations and tags. It can be 'list' (expands only the tags), 'full' (expands the tags and operations) or 'none' (expands nothing).                                                                         |
+| DeepLinking              | bool   | true       | If set to true, enables deep linking for tags and operations. See the Deep Linking documentation for more information.                                                                                                                                      |
+| DefaultModelsExpandDepth | int    | 1          | Default expansion depth for models (set to -1 completely hide the models).                                                                                                                                                                                  |
+| InstanceName             | string | "swagger"  | The instance name of the swagger document. If multiple different swagger instances should be deployed on one hertz router, ensure that each instance has a unique name (use the _--instanceName_ parameter to generate swagger documents with _swag init_). |
+| PersistAuthorization     | bool   | false      | If set to true, it persists authorization data and it would not be lost on browser close/refresh.                                                                                                                                                           |                                                                                            
+| Oauth2DefaultClientID    | string | ""         | If set, it's used to prepopulate the *client_id* field of the OAuth2 Authorization dialog.                                                                                                                                                                  |

example/basic/docs/docs.go

@@ -0,0 +1,56 @@
+// Package docs GENERATED BY SWAG; DO NOT EDIT
+// This file was generated by swaggo/swag
+package docs
+
+import "github.com/swaggo/swag"
+
+const docTemplate = `{
+    "schemes": {{ marshal .Schemes }},
+    "swagger": "2.0",
+    "info": {
+        "description": "{{escape .Description}}",
+        "title": "{{.Title}}",
+        "contact": {
+            "name": "hertz-contrib",
+            "url": "https://github.com/hertz-contrib"
+        },
+        "license": {
+            "name": "Apache 2.0",
+            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+        },
+        "version": "{{.Version}}"
+    },
+    "host": "{{.Host}}",
+    "basePath": "{{.BasePath}}",
+    "paths": {
+        "/ping": {
+            "get": {
+                "description": "测试Description",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "summary": "测试Summary",
+                "responses": {}
+            }
+        }
+    }
+}`
+
+// SwaggerInfo holds exported Swagger Info so clients can modify it
+var SwaggerInfo = &swag.Spec{
+	Version:          "1.0",
+	Host:             "localhost:8888",
+	BasePath:         "/",
+	Schemes:          []string{"http"},
+	Title:            "HertzTest",
+	Description:      "This is a demo using Hertz.",
+	InfoInstanceName: "swagger",
+	SwaggerTemplate:  docTemplate,
+}
+
+func init() {
+	swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
+}

example/basic/docs/swagger.json

@@ -0,0 +1,36 @@
+{
+    "schemes": [
+        "http"
+    ],
+    "swagger": "2.0",
+    "info": {
+        "description": "This is a demo using Hertz.",
+        "title": "HertzTest",
+        "contact": {
+            "name": "hertz-contrib",
+            "url": "https://github.com/hertz-contrib"
+        },
+        "license": {
+            "name": "Apache 2.0",
+            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+        },
+        "version": "1.0"
+    },
+    "host": "localhost:8888",
+    "basePath": "/",
+    "paths": {
+        "/ping": {
+            "get": {
+                "description": "测试Description",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "summary": "测试Summary",
+                "responses": {}
+            }
+        }
+    }
+}

example/basic/docs/swagger.yaml

@@ -0,0 +1,25 @@
+basePath: /
+host: localhost:8888
+info:
+  contact:
+    name: hertz-contrib
+    url: https://github.com/hertz-contrib
+  description: This is a demo using Hertz.
+  license:
+    name: Apache 2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
+  title: HertzTest
+  version: "1.0"
+paths:
+  /ping:
+    get:
+      consumes:
+      - application/json
+      description: 测试Description
+      produces:
+      - application/json
+      responses: {}
+      summary: 测试Summary
+schemes:
+- http
+swagger: "2.0"