Swagger的使用

佚名 6年前 (2019-05-05) 随笔 1893人围观抢沙发百度已收录

1. 什么是Swagger

Swagger是定义API的语言，先用文本形式定义API，并生成可视化API；可以使用json, yaml, ini这三种文件格式

SRE实战互联网时代守护先锋，助力企业售后服务体系运筹帷幄！一键直达领取阿里云限量特价优惠。

2. json与yaml与ini的优缺点

json

格式比较麻烦，使用大括号，容易出错

yaml

使用具备层级结构的文本，比较方便，且不易出错

ini

只能定义特别简单的API

3. 搭建Swagger环境

a. 在本地安装Swagger环境

b. 使用线上的Swagger环境

http://editor.swagger.io/

4. 使用yaml定义API的例子

例如：

swagger.yaml

swagger: '2.0'
info:
  version: 1.0.0
  title: 标签服务接口
  description: 这是标签服务的RestAPI接口定义
schemes:
  - http
  - https
host: tag.api.local.chinahanguang.com
basePath: /index.php/tag
paths:
  /list-tree:
    get:
      tags: 
      - "tag"
      summary: 获取标签树列表
      description: 返回标签列表的树形结构
      produces:
      - "application/xml"
      - "application/json"
      parameters:
      - name: "platform"
        in: "query"
        description: "平台唯一标识"
        required: true
        type: "string"
      - name: "user"
        in: "query"
        description: "用户唯一标识"
        required: false
        type: "string"
      - name: "tag_code_path"
        in: "query"
        description: "标签编码从父级至子级使用文件目录分隔符拼接"
        required: false
        type: "string"
      - name: "deep"
        in: "query"
        description: "从叶子标签开始计算的深度，0代表无限级深度"
        required: false
        type: "string"
      responses:
        200:
          description: "返回正确结果"
          schema:
            properties:
              code:
                type: "integer"
                description: "返回码"
              ret:
                type: "array"
                items:
                  $ref: "#/definitions/Tag"
        400:
          description: "返回错误码信息"
          
definitions:
  Tag:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
      platform:
        type: "string"
        format: ""
      user:
        type: "string"
        format: ""
      tag_name:
        type: "string"
        format: ""
      tag_code:
        type: "string"
        format: ""
      tag_type:
        type: "integer"
        format: ""
      tag_icon:
        type: "string"
        format: ""
      tag_sequence:
        type: "integer"
        format: ""
      tag_remark:
        type: "string"
        format: ""
      created_at:
        type: "integer"
        format: ""
      updated_at:
        type: "integer"
        format: ""
      is_del:
        type: "integer"
        format: ""
      children:
        type: "array"
        items:
          $ref: "#/definitions/Tag"
    xml:
      name: "Tag"

swagger.json

{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "标签服务接口",
    "description": "这是标签服务的RestAPI接口定义"
  },
  "schemes": [
    "http",
    "https"
  ],
  "host": "tag.api.local.chinahanguang.com",
  "basePath": "/index.php/tag",
  "paths": {
    "/list-tree": {
      "get": {
        "tags": [
          "tag"
        ],
        "summary": "获取标签树列表",
        "description": "返回标签列表的树形结构",
        "produces": [
          "application/xml",
          "application/json"
        ],
        "parameters": [
          {
            "name": "platform",
            "in": "query",
            "description": "平台唯一标识",
            "required": true,
            "type": "string"
          },
          {
            "name": "user",
            "in": "query",
            "description": "用户唯一标识",
            "required": false,
            "type": "string"
          },
          {
            "name": "tag_code_path",
            "in": "query",
            "description": "标签编码从父级至子级使用文件目录分隔符拼接",
            "required": false,
            "type": "string"
          },
          {
            "name": "deep",
            "in": "query",
            "description": "从叶子标签开始计算的深度，0代表无限级深度",
            "required": false,
            "type": "integer"
          }
        ],
        "responses": {
          "200": {
            "description": "返回正确结果",
            "schema": {
              "properties": {
                "code": {
                  "type": "integer",
                  "description": "返回码"
                },
                "ret": {
                  "type": "array",
                  "items": {
                    "$ref": "#/definitions/Tag"
                  }
                }
              }
            }
          },
          "400": {
            "description": "返回错误码信息"
          }
        }
      }
    }
  },
  "definitions": {
    "Tag":{
      "type": "object",
      "properties": {
        "id":{
          "type": "integer",
          "format": "int64"
        },
        "platform":{
          "type": "string",
          "format": ""
        },
        "user":{
          "type": "string",
          "format": ""
        },
        "tag_name":{
          "type": "string",
          "format": ""
        },
        "tag_code":{
          "type": "string",
          "format": ""
        },
        "tag_type":{
          "type": "integer",
          "format": "int64"
        },
        "tag_icon":{
          "type": "string",
          "format": ""
        },
        "tag_sequence":{
          "type": "integer",
          "format": "int64"
        },
        "tag_remark":{
          "type": "integer",
          "format": "int64"
        },
        "created_at":{
          "type": "integer",
          "format": "int64"
        },
        "updated_at":{
          "type": "integer",
          "format": "int64"
        },
        "is_del":{
          "type": "integer",
          "format": "int64"
        },
        "children":{
          "type": "array",
          "items": {
            "$ref": "#/definitions/Tag"
          }
        }
      }
    }
  }
}