基于react使用swaggerUI创建高质量的API文档

        现在多数的项目开发中，网站和移动端都需要进行数据交互和对接，这少不了使用REST编写API接口这种场景。 特别是不同开发小组协作时，就更需要以规范和文档作为标准和协作基础。良好的文档可以减少沟通成本，达到事半功倍的效果。

        有时对一些API说明的理解比较模糊，总想着能直接验证一下自己的理解就好了，而不是需要去项目写测试代码来验证自己的想法。 即API文档应具备直接执行能力，这种能力类似word,wiki等是无法提供。 SwaggerUI就是这样一种利器，基于html+javascript实现，倾向于在线文档和测试，使用和集成十分简单，能容易地生成不同模块下的API列表， 每个API接口描述和参数、请求方法都能定制并直接测试得到直观的响应数据。

        体验SwaggerUI最好的方法就是看下官网提供的demo，看过之后相信你一定会兴奋不已。

 SwaggerUI.js

import React, { Component } from 'react';
import { Scrollbars } from 'react-custom-scrollbars'
import SwaggerUI from "swagger-ui-react"
import swaggerData from './swaggerData.js'
import "swagger-ui-react/swagger-ui.css"
import './index.scss'

class App extends Component {
  render() {
    return (
      	<Scrollbars>
        		<SwaggerUI spec={swaggerData} />
        </Scrollbars>
    );
  }
}

export default App;

swaggerDataBase.js

import axios from 'axios'

const isDev = process.env.NODE_ENV === 'development';

let host = ''

if (isDev) {
  var str = axios.defaults.baseURL
  var reg = /http(s)?://([A-Za-z0123456789:.]+)/S+/;
  var result = reg.exec(str);
  if (result) {
    host = result[2]
  }
} else {
  var str = window.location.href
  var reg = /http(s)?://([A-Za-z0123456789:.]+)/S+/;
  var result = reg.exec(str);
  if (result) {
    host = result[2]
  }
}

let swaggerDataBase = {
  "swagger": "2.0",
  "info": {
    "description": "全新的接口文档",
    "version": "6.1.0",
    "title": "Baidu API",
    "termsOfService": "http://swagger.io/terms/",
    "contact": {
      "email": "apiteam@swagger.io"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "host": host,
  "basePath": "/api/v2",
  "tags": [ 
    {
      "name": "baidu_task",
      "description": "baidu任务相关接口",
      "externalDocs": {
        "description": "Find out more",
        "url": "http://swagger.io"
      }
    },    
    {
      "name": "baidu_systemset",
      "description": "baidu系统设置相关接口",
      "externalDocs": {
        "description": "Find out more",
        "url": "http://swagger.io"
      }
    },
  ],
  "schemes": ["https", "http"],
  "paths": {
  },  
}

export default swaggerDataBase

swaggerData.js

import Store from '@store'
import swaggerDataBase from './swaggerDataBase.js'

const token = Store.getState().getIn(['user', 'token'])
let Authorization = 'Bearer ' + token

//安全配置和备份管理
let security = {
  //备份管理--分页查找
  "/baidu/system/backup": {
    "get": {
      "tags": ["baidu_systemset"],
      "summary": "备份管理--分页查找",
      "description": "备份管理--分页查找",
      "operationId": "backup",
      "produces": ["application/xml", "application/json"],
      "parameters": [
        {
          "name": "Authorization",
          "in": "header",
          "description": "Authorization",
          "required": false,
          "type": "string",
          value: Authorization,
          "collectionFormat": "1"
        },
        {
          "name": "type",
          "in": "query",
          "description": "系统备份：system， 日志备份：log",
          "required": true,
          "type": "string",
          value:'system',
          "collectionFormat": "multi"
        }, 
        {
          "name": "page",
          "in": "query",
          "description": "页码",
          "required": true,
          "type": "string",
          value:'1',
          "collectionFormat": "multi"
        },  
        {
          "name": "search",
          "in": "query",
          "description": "搜索字段",
          "required": false,
          "type": "string",
          value:'',
          "collectionFormat": "multi"
        },         
      ],
      "responses": {
        "200": {
          "description": "successful operation",
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/definitions/Pet"
            }
          }
        },
        "400": {
          "description": "Invalid status value"
        }
      },
      "security": [{
        "petstore_auth": ["write:pets", "read:pets"]
      }]
    },    
  },  
}

//get post put delete
let role = {
  //角色管理
  "/baidu/role": {
    "get": {
      "tags": ["baidu_systemset"],
      "summary": "角色管理--查询所有角色",
      "description": "角色管理--查询所有角色",
      "operationId": "get_role",
      "produces": ["application/xml", "application/json"],
      "parameters": [
        {
          "name": "Authorization",
          "in": "header",
          "description": "Authorization",
          "required": false,
          "type": "string",
          value: Authorization,
          "collectionFormat": "1"
        }
      ],
      "responses": {
        "200": {
          "description": "successful operation",
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/definitions/Pet"
            }
          }
        },
        "400": {
          "description": "Invalid status value"
        }
      },
      "security": [{
        "petstore_auth": ["write:pets", "read:pets"]
      }]
    },
    "post": {
      "tags": ["baidu_systemset"],
      "summary": "角色管理--添加角色",
      "description": "角色管理--添加角色",
      "operationId": "add_role",
      "consumes": ["application/json", "application/xml"],
      "produces": ["application/xml", "application/json"],
      "parameters": [{
          "name": "Authorization",
          "in": "header",
          "description": "Authorization",
          "required": false,
          "type": "string",
          value: Authorization,
          "collectionFormat": "1"
        },
        {
          "in": "body",
          "name": "body",
          "description": "角色管理--添加角色",
          "required": true,
          "schema": {
            type: "object",
            properties: {
              role_name: {
                type: "string",
                "example": 'role1',
                description: '角色名称'
              },
              is_superuser: {
                type: "integer",
                "example": 0,
                description: '-1:访客 0:普通用户 1:系统管理员'
              },              
            }
          }
        }
      ],
      "responses": {
        "405": {
          "description": "Invalid input"
        }
      },
      "security": [{
        "petstore_auth": ["write:pets", "read:pets"]
      }]
    },
    "put": {
      "tags": ["baidu_systemset"],
      "summary": "角色管理--修改角色",
      "description": "角色管理--修改角色",
      "operationId": "put_role",
      "consumes": ["application/json", "application/xml"],
      "produces": ["application/xml", "application/json"],
      "parameters": [{
          "name": "Authorization",
          "in": "header",
          "description": "Authorization",
          "required": false,
          "type": "string",
          value: Authorization,
          "collectionFormat": "1"
        },
        {
          "in": "body",
          "name": "body",
          "description": "角色管理--修改角色",
          "required": true,
          "schema": {
            type: "object",
            properties: {
              role_id: {
                type: "integet",
                "example": 1,
                description: '角色id'
              },                  
              role_name: {
                type: "string",
                "example": 'role1',
                description: '角色名称'
              },
              is_superuser: {
                type: "integer",
                "example": 0,
                description: '-1:访客 0:普通用户 1:系统管理员'
              },                 
            }
          }
        }
      ],
      "responses": {
        "405": {
          "description": "Invalid input"
        }
      },
      "security": [{
        "petstore_auth": ["write:pets", "read:pets"]
      }]
    },
    "delete": {
      "tags": ["baidu_systemset"],
      "summary": "角色管理--删除角色",
      "description": "角色管理--删除角色",
      "operationId": "delete_role",
      "consumes": ["application/json", "application/xml"],
      "produces": ["application/xml", "application/json"],
      "parameters": [{
          "name": "Authorization",
          "in": "header",
          "description": "Authorization",
          "required": false,
          "type": "string",
          value: Authorization,
          "collectionFormat": "1"
        },
        {
          "in": "body",
          "name": "body",
          "description": "角色管理--删除角色",
          "required": true,
          "schema": {
            type: "object",
            properties: {
              role_id: {
                type: "integet",
                "example": 1,
                description: '角色id'
              }
            }
          }
        }
      ],
      "responses": {
        "405": {
          "description": "Invalid input"
        }
      },
      "security": [{
        "petstore_auth": ["write:pets", "read:pets"]
      }]
    }             
  },     
}

//动态url
let plugin = {
  //动态url
  "/baidu/component_info/{component_id}": {
    "get": {
      "tags": ["baidu_task"],
      "summary": "动态url",
      "description": "动态url",
      "operationId": "component_info",
      "produces": ["application/xml", "application/json"],
      "parameters": [
        {
          "name": "Authorization",
          "in": "header",
          "description": "Authorization",
          "required": false,
          "type": "string",
          value: Authorization,
          "collectionFormat": "1"
        },
        {
          "name": "component_id",
          "in": "path",
          "description": "id",
          "required": true,
          "type": "string",
          value: '495519',
        }        
      ],
      "responses": {
        "200": {
          "description": "successful operation",
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/definitions/Pet"
            }
          }
        },
        "400": {
          "description": "Invalid status value"
        }
      },
      "security": [{
        "petstore_auth": ["write:pets", "read:pets"]
      }]
    },          
  },  
}

swaggerDataBase.paths = {
  ...swaggerDataBase.paths, 
  ...security, 
  ...role,
  ...plugin,
}

export default swaggerDataBase

参考链接：http://www.sosoapi.com/pass/faq/swagger.htm