OpenAPI 3

Submitted by Lizhe on Wed, 11/18/2020 - 05:38

这里有一个复杂的例子

 

/ Package Helloworld 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 main

 

import (

    "encoding/json"

    "io"

    "log"

    "net/http"

)

 

// swagger:operation GET /pets getPet

//

// Returns all pets from the system that the user has access to

//

// Could be any pet

//

// ---

// produces:

// - application/json

// - application/xml

// - text/xml

// - text/html

// parameters:

// - name: tags

//   in: query

//   description: tags to filter by

//   required: false

//   type: array

//   items:

//     type: string

//   collectionFormat: csv

// - name: limit

//   in: query

//   description: maximum number of results to return

//   required: false

//   type: integer

//   format: int32

// responses:

//   '200':

//     description: pet response

//     schema:

//       type: object

//       items:

//         "$ref": "#/responses/HelloResponse"

//   default:

//     description: unexpected error

//     type: object

//     schema:

//       "$ref": "#/responses/HelloResponse"

func hello(w http.ResponseWriter, r *http.Request) {

    resp := ResponseMessage{Message: "hello world"}

    res_json, _ := json.Marshal(resp)

    io.WriteString(w, string(res_json))

}

func main() {

    http.HandleFunc("/hello", hello)

    if err := http.ListenAndServe(":8080", nil); err != nil {

        log.Fatal(err)

    }

}

 

// HelloResponse is an response with helloworld message.

//

// swagger:response HelloResponse

type ResponseMessage struct {

    Message string

}

 

 

不过这里我不打算使用这么复杂的

 稍作修改

// Package Helloworld 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 main

 

import (

    "encoding/json"

    "io"

    "log"

    "net/http"

)

 

// swagger:operation GET /hello tag1 tag2 login

//

// Returns all pets from the system that the user has access to

//

// Could be any pet

//

// ---

// produces:

// - application/json

// parameters:

// - name: name

//   in: query

//   description: user name

//   required: true

//   type: string

// - name: password

//   in: query

//   description: user password

//   required: true

//   type: string

// responses:

//   '200':

//     description: login success

//     schema:

//       type: object

//       items:

//         "$ref": "#/responses/HelloResponse"

//   default:

//     description: unexpected error

//     type: object

//     schema:

//       "$ref": "#/responses/HelloResponse"

func hello(w http.ResponseWriter, r *http.Request) {

    resp := ResponseMessage{Message: "hello world"}

    res_json, _ := json.Marshal(resp)

    io.WriteString(w, string(res_json))

}

func main() {

    http.HandleFunc("/hello", hello)

    if err := http.ListenAndServe(":8080", nil); err != nil {

        log.Fatal(err)

    }

}

 

// HelloResponse is an response with helloworld message.

//

// swagger:response HelloResponse

type ResponseMessage struct {

    Message string

}

 

 

经过处理之后生成的json内容为

 

 

{

  "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": "API.",

    "version": "0.0.1"

  },

  "host": "localhost",

  "paths": {

    "/hello": {

      "get": {

        "description": "Could be any pet",

        "produces": [

          "application/json"

        ],

        "tags": [

          "tag1",

          "tag2"

        ],

        "summary": "Returns all pets from the system that the user has access to",

        "operationId": "login",

        "parameters": [

          {

            "type": "string",

            "description": "user name",

            "name": "name",

            "in": "query",

            "required": true

          },

          {

            "type": "string",

            "description": "user password",

            "name": "password",

            "in": "query",

            "required": true

          }

        ],

        "responses": {

          "200": {

            "description": "login success",

            "schema": {

              "type": "object",

              "items": {

                "$ref": "#/responses/HelloResponse"

              }

            }

          },

          "default": {

            "description": "unexpected error",

            "schema": {

              "$ref": "#/responses/HelloResponse"

            }

          }

        }

      }

    }

  },

  "responses": {

    "HelloResponse": {

      "description": "HelloResponse is an response with helloworld message.",

      "headers": {

        "Message": {

          "type": "string"

        }

      }

    }

  }

}

 

 

20201118014403