1
 2
 3
 4
 5
 6
 7
 8
 9
10

swagger: "2.0"
info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification
schemes:
  - https
host: simple.api
basePath: /openapi101
paths: {}

1
2
3
4
5

# brew
brew tap go-swagger/go-swagger
brew install go-swagger
# go get
go get -u github.com/go-swagger/go-swagger/cmd/swagger

1
2
3
4

# 根源源码生成一个swagger文档，他的类型可以是json或者是yaml，根据你的后缀名
swagger generate spec -o ./swagger.json/yaml
# 测试这个swagger文档是否有效
swagger validate ./swagger.json/yaml

1

The swagger spec at "swagger.json/yaml" is valid against swagger specification 2.0

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

// Package classification Petstore API.
//
// the purpose of this application is to provide an application
// that is using plain go code to define an API
//
// This should demonstrate all the possible comment annotations
// that are available to turn go code into a fully compliant swagger 2.0 spec
//
// Terms Of Service:
//
// there are no TOS at this moment, use at your own risk we take no responsibility
//
//     Schemes: http, https
//     Host: localhost
//     BasePath: /v2
//     Version: 0.0.1
//     License: MIT http://opensource.org/licenses/MIT
//     Contact: John Doe<john.doe@example.com> http://john.doe.com
//
//     Consumes:
//     - application/json
//     - application/xml
//
//     Produces:
//     - application/json
//     - application/xml
//
//     Security:
//     - api_key:
//
//     SecurityDefinitions:
//     api_key:
//          type: apiKey
//          name: KEY
//          in: header
//     oauth2:
//         type: oauth2
//         authorizationUrl: /oauth2/auth
//         tokenUrl: /oauth2/token
//         in: header
//         scopes:
//           bar: foo
//         flow: accessCode
//
//     Extensions:
//     x-meta-value: value
//     x-meta-array:
//       - value1
//       - value2
//     x-meta-array-obj:
//       - name: obj
//         value: field
//
// swagger:meta
package classification

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

---
swagger: '2.0'
consumes:
  - application/json
  - application/xml
produces:
  - application/json
  - application/xml
schemes:
  - http
  - https
info:
  description: "the purpose of this application is to provide an application\nthat is using plain go code to define an API\n\nThis should demonstrate all the possible comment annotations\nthat are available to turn go code into a fully compliant swagger 2.0 spec"
  title: 'Petstore API.'
  termsOfService: 'there are no TOS at this moment, use at your own risk we take no responsibility'
  contact: {name: 'John Doe', url: 'http://john.doe.com', email: john.doe@example.com}
  license: {name: MIT, url: 'http://opensource.org/licenses/MIT'}
  version: 0.0.1
host: localhost
basePath: /v2
x-meta-value: value
x-meta-array:
  - value1
  - value2
x-meta-array-obj:
  - name: obj
    value: field

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// ServeAPI serves the API for this record store
func TestSwagger(c *gin.Context) {
    // swagger:route GET /pets PetsUsers listPets
    //
    // Lists pets filtered by some parameters.
    //
    // This will show all available pets by default.
    // You can get the pets that are out of stock
    //
    //     Responses:
    //       default: genericError
    //       200: someResponse
    //       400: validationError

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

---
paths:
  "/pets":
    get:
      operationId: listPets
      summary: Lists pets filtered by some parameters.
      description: "This will show all available pets by default.\nYou can get the pets that are out of stock"
      tags:
      - PetsUsers
      responses:
        default:
          $ref: "#/responses/genericError"
        200:
          $ref: "#/responses/someResponse"
        422:
          $ref: "#/responses/validationError"

1

// Schemes: http, https, ws, wss

1
2
3
4
5
6
7

// consumes:
// - application/json
// - application/x-protobuf
//
// produces:
// - application/json
// - application/x-protobuf

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// security:
//   api_key:
//   oauth: read, write
//   basicAuth:
//      type: basic
//   token:
//      type: apiKey
//      name: token
//      in: query
//   accessToken:
//      type: apiKey
//      name: access_token
//      in: query

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

// ServeAPI serves the API for this record store
func TestSwagger(c *gin.Context) {
    // swagger:operation GET /repo/{author} repos repoList
    // ---
    // summary: List the repositories owned by the given author.
    // description: If author length is between 6 and 8, Error Not Found (404) will be returned.
    // parameters:
    // - name: author
    //   in: path
    //   description: username of author
    //   type: string
    //   required: true
    // responses:
    //   "200":
    //     "$ref": "#/responses/reposResp"
    //   "404":
    //     "$ref": "#/responses/notFound"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// Request containing string
// swagger:parameters test_demo
type BarSliceParam struct {
    // a BarSlice has bars which are strings
    //
    // min items: 3
    // max items: 10
    // unique: true
    // Required: true
    // in: query
    Name string `json:"name"`
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

---
operations:
  "/":
    get:
      operationId: test_demo
      parameters:
        - name: name
          in: query
          maxLength: 10
          minLength: 3
          unique: true
          Required: true

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

//  swagger:parameters userBind
type userLoginWrapper struct {
	// in: body
	Body UserBindRequest
}
type UserLoginRequest struct {
	//  用户名
	UserName string `json:"user_name"`
	//  id
	Id string `json:"id"`
}

1
2

// consumes:
//   - application/json

1
2
3
4
5

{
     "msg": "OK"
     "code":200, // Code containing HTTP status CODE
     "data":{} // Data containing actual response data
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// A ValidationError is an error that is used when the required input fails validation.
// swagger:response validationError
type ValidationError struct {
    // The error message
    // in: body
    Body struct {
        // The validation message
        //
        // Required: true
        Message string
        // An optional field name to which this validation applies
        FieldName string
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// 成功或失败返回的数据格式
// swagger:response SwaggerResponse
type SwaggerWapper struct {
    // The error message
    // in: body
    Body ResponseMessage
}

type ResponseMessage struct {
    // 返回的code码
    // Required: true
    Code int         `json:"code"`
    Msg  string      `json:"msg"`
    Data interface{} `json:"data"`
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

---
responses:
  validationError:
    description: A ValidationError is an error that is used when the required input fails validation.
    schema:
      type: object
      description: The error message
      required:
      - Message
      properties:
        Message:
          type: string
          description: The validation message
          example: Expected type int
        FieldName:
          type: string
          description: an optional field name to which this validation applies

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

responses:
  SwaggerResponse:
    description: 成功或失败返回的数据格式
    schema:
      $ref: '#/definitions/ResponseMessage'
definitions:
  ResponseMessage:
    properties:
      code:
        description: 返回的code码
        type: integer
      data:
        type: object
      msg:
        type: string
    required:
    - code
    type: object

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

package service

import (
    "encoding/json"
    "fmt"
    "net/http"
    "strconv"
    "user.server/models"
    "crypto/md5"
    "errors"
    "github.com/Sirupsen/logrus"
    "github.com/gorilla/mux"
)

type GetUserParam struct {
    Id int `json:"id"`
}

func GetOneUser(w http.ResponseWriter, r *http.Request) {
    defer r.Body.Close()
    decoder := json.NewDecoder(r.Body)
    var param GetUserParam
    err := decoder.Decode(&param)
    if err != nil {
        WriteResponse(w, ErrorResponseCode, "request param is invalid, please check!", nil)
        return
    }

    // get user from db
    user, err := models.GetOne(strconv.Itoa(param.Id))
    if err != nil {
        logrus.Warn(err)
        WriteResponse(w, ErrorResponseCode, "failed", nil)
        return
    }
    WriteResponse(w, SuccessResponseCode, "success", user)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// Package classification User API.
//
// The purpose of this service is to provide an application
// that is using plain go code to define an API
//
//      Host: localhost
//      Version: 0.0.1
//
// swagger:meta
package service

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "swagger": "2.0",
  "info": {
    "description": "The purpose of this service is to provide an application\nthat is using plain go code to define an API",
    "title": "User API.",
    "version": "0.0.1"
  },
  "host": "localhost",
  "paths": {}
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

// swagger:parameters getSingleUser
type GetUserParam struct {
    // an id of user info
    //
    // Required: true
    // in: path
    Id int `json:"id"`
}

func GetOneUser(w http.ResponseWriter, r *http.Request) {
    // swagger:route GET /users/{id} users getSingleUser
    //
    // get a user by userID
    //
    // This will show a user info
    //
    //     Responses:
    //       200: UserResponse
    decoder := json.NewDecoder(r.Body)
    var param GetUserParam
    err := decoder.Decode(&param)
    if err != nil {
        WriteResponse(w, ErrorResponseCode, "request param is invalid, please check!", nil)
        return
    }

    // get user from db
    user, err := models.GetOne(strconv.Itoa(param.Id))
    if err != nil {
        logrus.Warn(err)
        WriteResponse(w, ErrorResponseCode, "failed", nil)
        return
    }
    WriteResponse(w, SuccessResponseCode, "success", user)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// swagger:parameters getSingleUser
// 定义一个 Person 结构体，用来绑定 url query
type Person struct {
	// an id of user info
	//
	// Required: true
	// in: query
	Name string `form:"name" json:"name"` // 使用成员变量标签定义对应的参数名
	// an address of user info
	//
	// Required: true
	// in: query
	Address string `form:"address" json:"address"`
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// User Info
//
// swagger:response UserResponse
type UserWapper struct {
    // in: body
    Body ResponseMessage
}

type ResponseMessage struct {
    Code    int         `json:"code"`
    Message string      `json:"message"`
    Data    interface{} `json:"data"`
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

func UpdateUser(w http.ResponseWriter, r *http.Request) {
    defer r.Body.Close()
    // decode body data into user struct
    decoder := json.NewDecoder(r.Body)
    user := models.User{}
    err := decoder.Decode(&user)
    if err != nil {
        WriteResponse(w, ErrorResponseCode, "user data is invalid, please check!", nil)
        return
    }

    // check if user exists
    data, err := models.GetUserById(user.Id)
    if err != nil {
        logrus.Warn(err)
        WriteResponse(w, ErrorResponseCode, "query user failed", nil)
        return
    }
    if data.Id == 0 {
        WriteResponse(w, ErrorResponseCode, "user not exists, no need to update", nil)
        return
    }

    // update
    _, err = models.Update(user)
    if err != nil {
        WriteResponse(w, ErrorResponseCode, "update user data failed, please try again!", nil)
        return
    }
    WriteResponse(w, SuccessResponseCode, "update user data success!", nil)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

package service

import "user.server/models"

// swagger:parameters UpdateUserResponseWrapper
type UpdateUserRequest struct {
    // in: body
    Body models.User
}

// Update User Info
//
// swagger:response UpdateUserResponseWrapper
type UpdateUserResponseWrapper struct {
    // in: body
    Body ResponseMessage
}

// swagger:route POST /users users UpdateUserResponseWrapper
//
// Update User
//
// This will update user info
//
//     Responses:
//       200: UpdateUserResponseWrapper

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// 测试标题
//
// 测试介绍
//
// Host: localhost:8888
// Version: 1.0.0
//
// swagger:meta
package main

func main() {
	router := engine.InitGinEngine()
	router.GET("gettest", GetTest)
	router.Run(":" + Port)
}

func GetTest(c *gin.Context) {
	var req adapter.GetTestRequest
	// 将 url 查询参数和person绑定在一起
	_ = c.ShouldBindQuery(&req)
	res := adapter.GetTestResponse{}
	comm.SetResultMsg(c, 0, res, "")
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

package adapter

// swagger:operation GET /gettest GetTest
// ---
// summary: 接口简介.
// description: 接口说明
// responses:
//   "200":
//     description: 返回值
//     schema:
//       properties:
//         code:
//           format: int64
//           type: integer
//           example: 0
//         data:
//           $ref: '#/definitions/GetTestResponse'
//         message:
//           type: string
//           example: "success"

// 结构体GetTestRequest介绍
//  swagger:parameters GetTest
type GetTestRequest struct {
	//  参数A介绍
	//  Required: true
	//  in: query
	Name string `form:"name" json:"name"`

	//  参数B介绍
	//  Required: true
	//  in: query
	Address string `form:"address" json:"address"`
}

// GetTestResWrapper介绍
// swagger:response GetTestResWrapper
type getTestResWrapper struct {
	// The error message
	// in: body
	Body GetTestResponse
}

// GetTestResult介绍
type GetTestResponse struct {
	// 学生姓名
	//example: 小明
	Name string `form:"name" json:"name"`
	//  学生住址
	//example: 北京
	Address string `form:"address" json:"address"`
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

definitions:
  GetTestResponse:
    description: GetTestResult介绍
    properties:
      address:
        description: 学生住址
        example: 北京
        type: string
        x-go-name: Address
      name:
        description: 学生姓名
        example: 小明
        type: string
        x-go-name: Name
    type: object
    x-go-package: suyang/example/go-swagger/adapter
host: localhost:8888
info:
  description: 测试介绍
  title: 测试标题
  version: 1.0.0
paths:
  /gettest:
    get:
      description: 接口说明
      operationId: GetTest
      parameters:
      - description: 参数A介绍
        in: query
        name: name
        required: true
        type: string
        x-go-name: Name
      - description: 参数B介绍
        in: query
        name: address
        required: true
        type: string
        x-go-name: Address
      responses:
        "200":
          description: 返回值
          schema:
            properties:
              code:
                example: 0
                format: int64
                type: integer
              data:
                $ref: '#/definitions/GetTestResponse'
              message:
                example: success
                type: string
      summary: 接口简介.
responses:
  GetTestResWrapper:
    description: GetTestResWrapper介绍
    schema:
      $ref: '#/definitions/GetTestResponse'
swagger: "2.0"