基于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 swaggerDataBaseswaggerData.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