## Golang不一样的swagger
### 什么是swagger
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
### swag
[zc2638/swag](https://github.com/zc2638/swag) 是一个轻量级的库，可以为Go项目生成swagger json。
没有代码生成，没有框架约束，无须使用注释信息去实现伪注解，只有一个简单的swagger结构定义。
原始代码库savaki/swag，由于作者不再维护，故在此基础上的修改版本。
### 使用
#### 获取
```
go get github.com/zc2638/swag
```
#### Endpoint
swag提供了一个单独的程序包，endpoint用来创建一个特定的接口定义，这些接口定义可以通过swag.Endpoints(...)挂载。
在这个简单的示例中，我们生成一个接口定义来获取所有pet。接口定义只需要接口请求方式和路径，为了使swagger定义完整，需要约束返回结果。
```go
allPets := endpoint.New(http.MethodGet, "/pet", endpoint.ResponseSuccess())
```
当然，也可以指定多个自定义返回结果：
```go
allPets := endpoint.New("get", "/pet",
endpoint.Summary("Return all the pets"),
endpoint.Response(http.StatusOk, Pet{}, "Successful operation"),
endpoint.Response(http.StatusInternalServerError, Error{}, "Oops ... something went wrong"),
)
```
#### Walk
Walk是简化所有接口定义遍历的方法。有关如何使用Walk方法将接口定义绑定到指定框架的路由上，请参见下面的完整示例。
```go
api := swag.New(
swag.Title("Swagger Petstore"),
swag.Endpoints(post, get),
)
router := gin.Default()
// iterate over each endpoint, if we've defined a handler, we can use it to bind to the router. We're using ```gin``
// in this example, but any web framework will do.
api.Walk(func(path string, endpoint *swagger.Endpoint) {
h := endpoint.Handler.(func(c *gin.Context))
path = swag.ColonPath(path)
router.Handle(endpoint.Method, path, h)
})
```
#### 完整示例
```go
// Copyright 2020 zc2638
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
package main
import (
"io"
"net/http"
"github.com/zc2638/swag"
"github.com/zc2638/swag/endpoint"
"github.com/zc2638/swag/swagger"
)
func handle(w http.ResponseWriter, req *http.Request) {
io.WriteString(w, req.Method+" - Insert your code here")
}
// Category example from the swagger pet store
type Category struct {
ID int64 `json:"category"`
Name string `json:"name" enum:"dog,cat"`
}
// Pet example from the swagger pet store
type Pet struct {
ID int64 `json:"id"`
Category Category `json:"category"`
Name string `json:"name" required:"" example:"张三" desc:"名称"`
PhotoUrls []string `json:"photoUrls"`
Tags []string `json:"tags"`
Test
}
type Test struct {
A string `json:"a"`
}
func main() {
post := endpoint.New("post", "/pet", endpoint.Summary("Add a new pet to the store"),
endpoint.Handler(handle),
endpoint.Description("Additional information on adding a pet to the store"),
endpoint.Body(Pet{}, "Pet object that needs to be added to the store", true),
endpoint.Response(http.StatusOK, "Successfully added pet", endpoint.Schema(Pet{})),
endpoint.Security("petstore_auth", "read:pets", "write:pets"),
)
get := endpoint.New("get", "/pet/{petId}", endpoint.Summary("Find pet by ID"),
endpoint.Handler(handle),
endpoint.Path("petId", "integer", "ID of pet to return", true),
endpoint.Response(http.StatusOK, "successful operation", endpoint.Schema(Pet{})),
endpoint.Security("petstore_auth", "read:pets"),
)
api := swag.New(
swag.Endpoints(post, get),
swag.Security("petstore_auth", "read:pets"),
swag.SecurityScheme("petstore_auth",
swagger.OAuth2Security("accessCode", "http://example.com/oauth/authorize", "http://example.com/oauth/token"),
swagger.OAuth2Scope("write:pets", "modify pets in your account"),
swagger.OAuth2Scope("read:pets", "read your pets"),
),
)
for path, endpoints := range api.Paths {
http.Handle(path, endpoints)
}
enableCors := true
http.Handle("/swagger", api.Handler(enableCors))
http.ListenAndServe(":8080", nil)
}
```
可以使用内置方法```swag.New().Handler(false)```生成解析好的Swagger JSON定义。
指定Struct Tag生成额外内容：
- required: 是否必须
- desc: 描述
- description: 描述，作用同desc
- example: 默认示例
- enum: 枚举定义，逗号分隔
### 快速生成在线版本swagger
[参考官方UI](https://github.com/swagger-api/swagger-ui)
#### Webpack
[参考](https://github.com/swagger-api/swagger-ui/tree/master/docs/samples/webpack-getting-started)
#### Docker
> docker run -p 8080:8080 -e SWAGGER\_JSON\_URL=https://petstore.swagger.io/v1/swagger.json swaggerapi/swagger-ui
#### Kubernetes
swagger-ui.yaml
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: swagger-ui
labels:
app: swagger-ui
spec:
selector:
matchLabels:
app: swagger-ui
template:
metadata:
name: swagger-ui
labels:
app: swagger-ui
spec:
containers:
- name: swagger-ui
image: swaggerapi/swagger-ui:latest
env:
- name: SWAGGER_JSON_URL
value: 'https://petstore.swagger.io/v1/swagger.json'
---
apiVersion: v1
kind: Service
metadata:
name: swagger-ui
labels:
app: swagger-ui
spec:
ports:
- name: swagger-ui-80
port: 80
selector:
app: swagger-ui
type: NodePort
```
> kubectl app -f swagger-ui.yaml
<img width="100%" src="https://static.studygolang.com/210111/e908853fb0786972884954733597f9f0.png" />
### 最后
传送门：[**https://github.com/zc2638/swag**](https://github.com/zc2638/swag)
有疑问加站长微信联系（非本文作者）
