指南 / 教程

CentOS 7 搭建 Swagger API 文档管理系统

Swagger Editor & UI

在 CentOS 7 环境中搭建 Swagger Editor 和 Swagger UI 来管理 API 文档是一个常见的做法

准备条件

搭建 Swagger API 文档管理系统, 截止文章发布时配置

  • CentOS 7.8.2003 (Core)
  • Swagger Editor v3.14.0
  • Swagger UI v3.34.0
  • Node.js LTS Version: 12.18.4 (includes npm 6.14.6)

安装 Node.js

Node.js 官网文档 基于企业 Linux 的发行版 历史版本

安装编译依赖 

yum install gcc-c++ make

# or
yum groupinstall 'Development Tools'

安装 Node.js v12.x 

# As root
curl -sL https://rpm.nodesource.com/setup_12.x | bash -

yum install nodejs

验证安装

验证 Node.js 和 npm 安装是否成功

# 查看 Node.js 版本
node -v
v12.18.4

# 查看 npm 版本
npm -v
6.14.6

安装 Swagger-Editor

创建一个 swagger 目录 

cd swagger

下载 Swagger-Editor

下载最新版本的 Swagger Editor

wget https://github.com/swagger-api/swagger-editor/archive/v3.14.0.tar.gz
tar -xf v3.14.0.tar.gz

安装 http-server 

npm install -g http-server

启动 Swagger Editor 服务 

http-server swagger-editor           # 以 8080 端口启动项目
http-server -p 8082 swagger-editor   # 指定端口启动项目

http-server -p 8081 swagger-editor-3.14.0

Starting up http-server, serving swagger-editor-3.14.0
Available on:
  http://127.0.0.1:8081
Hit CTRL-C to stop the server

现在可以在浏览器访问 Swagger-Editor 了, 如 http://127.0.0.1:8081/

安装 Swagger-UI

回到 swagger 目录 

cd swagger

下载 Swagger-UI

下载并解压最新版本的 Swagger UI

wget https://github.com/swagger-api/swagger-ui/archive/v3.34.0.tar.gz
tar -xf v3.34.0.tar.gz

初始化 Node.js 项目

初始化 Node.js 项目, 创建 package.json 文件

npm init

# npm init
This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.

See `npm help init` for definitive documentation on these fields
and exactly what they do.

Use `npm install <pkg>` afterwards to install a package and
save it as a dependency in the package.json file.

Press ^C at any time to quit.
package name: (swagger-ui)
version: (3.34.0)
keywords:
author:
license: (Apache-2.0)
About to write to /root/swagger/swagger-ui-3.34.0/package.json:

{
  "name": "swagger-ui",
  "version": "3.34.0",
  "main": "dist/swagger-ui.js",
  "module": "dist/swagger-ui-es-bundle.js",
  "homepage": "https://github.com/swagger-api/swagger-ui",
  "repository": {
    "type": "git",
    "url": "git+ssh://git@github.com/swagger-api/swagger-ui.git"
  },
  "contributors": [
    " (in alphabetical order)",
    "Anna Bodnia <anna.bodnia@gmail.com>",
    "Buu Nguyen <buunguyen@gmail.com>",
    "Josh Ponelat <jponelat@gmail.com>",
    "Kyle Shockey <kyleshockey@gmail.com>",
    "Robert Barnwell <robert@robertismy.name>",
    "Sahar Jafari <shr.jafari@gmail.com>"
  ],
  "license": "Apache-2.0",
  "scripts": {
    "automated-release": "release-it -VV --config ./release/.release-it.json",
    "build": "run-p --aggregate-output build-core build-bundle build-standalone build-stylesheets build:es:bundle build:es:bundle:core",
    "build-bundle": "webpack --colors --config webpack/bundle.babel.js",
    "build-core": "webpack --colors --config webpack/core.babel.js",
    "build-standalone": "webpack --colors --config webpack/standalone.babel.js",
    "build-stylesheets": "webpack --colors --config webpack/stylesheets.babel.js",
    "build:es:bundle": "webpack --colors --config webpack/es-bundle.babel.js",
    "build:es:bundle:core": "webpack --colors --config webpack/es-bundle-core.babel.js",
    "predev": "npm install",
    "dev": "webpack-dev-server --config webpack/dev.babel.js",
    "deps-license": "license-checker --production --csv --out $npm_package_config_deps_check_dir/licenses.csv && license-checker --development --csv --out $npm_package_config_deps_check_dir/licenses-dev.csv",
    "deps-size": "webpack -p --config webpack/bundle.babel.js --json | webpack-bundle-size-analyzer >| $npm_package_config_deps_check_dir/sizes.txt",
    "deps-check": "run-s deps-license deps-size",
    "lint": "eslint --cache --ext \".js,.jsx\" src test",
    "lint-errors": "eslint --cache --quiet --ext \".js,.jsx\" src test",
    "lint-fix": "eslint --cache --ext \".js,.jsx\" src test --fix",
    "test": "run-s just-test-in-node test:unit-jest e2e-cypress lint-errors",
    "test-in-node": "run-s lint-errors just-test-in-node",
    "just-test-in-node": "cross-env BABEL_ENV=test mocha \"test/mocha/**/*.{js,jsx}\"",
    "test-e2e-cypress": "cypress run",
    "test-e2e-selenium": "sleep 3 && nightwatch test/e2e-selenium/scenarios/ --config test/e2e-selenium/nightwatch.json",
    "test:artifact": "run-s test:artifact:umd:bundle test:artifact:es:bundle test:artifact:es:bundle:core",
    "test:artifact:umd:bundle": "npm run build-bundle && cross-env BABEL_ENV=commonjs jest --config ./config/jest/jest.artifact-umd-bundle.config.js",
    "test:artifact:es:bundle": "npm run build:es:bundle && cross-env BABEL_ENV=commonjs jest --config ./config/jest/jest.artifact-es-bundle.config.js",
    "test:artifact:es:bundle:core": "npm run build:es:bundle:core && cross-env BABEL_ENV=commonjs jest --config ./config/jest/jest.artifact-es-bundle-core.config.js",
    "test:unit-jest": "cross-env BABEL_ENV=test jest --config ./config/jest/jest.unit.config.js",
    "e2e-initial-render": "nightwatch test/e2e-selenium/scenarios/ --config test/e2e-selenium/nightwatch.json --group initial-render",
    "mock-api": "json-server --watch test/e2e-selenium/db.json --port 3204",
    "hot-e2e-cypress-server": "webpack-dev-server --config webpack/dev-e2e.babel.js --content-base test/e2e-cypress/static",
    "hot-e2e-selenium-server": "webpack-dev-server --config webpack/dev-e2e.babel.js --content-base test/e2e-selenium/static",
    "e2e-cypress": "run-p -r hot-e2e-cypress-server mock-api test-e2e-cypress",
    "dev-e2e-cypress-open": "cypress open",
    "dev-e2e-cypress": "run-p -r hot-e2e-cypress-server mock-api dev-e2e-cypress-open",
    "e2e-selenium": "run-p -r hot-e2e-selenium-server mock-api test-e2e-selenium",
    "open-static": "node -e \"require('open')('http://localhost:3002')\"",
    "security-audit": "run-s -sc security-audit:all security-audit:prod",
    "security-audit:prod": "npm-audit-ci-wrapper -p -t low",
    "security-audit:all": "npm-audit-ci-wrapper -t moderate",
    "serve-static": "http-server dist/ -i -a 0.0.0.0 -p 3002",
    "start": "npm-run-all --parallel serve-static open-static"
  },
  "dependencies": {
    "@babel/runtime-corejs3": "^7.11.2",
    "@braintree/sanitize-url": "^4.0.0",
    "@kyleshockey/object-assign-deep": "^0.4.2",
    "@kyleshockey/xml": "^1.0.2",
    "base64-js": "^1.2.0",
    "classnames": "^2.2.6",
    "core-js": "^2.6.11",
    "css.escape": "1.5.1",
    "deep-extend": "0.6.0",
    "dompurify": "^2.0.7",
    "ieee754": "^1.1.13",
    "immutable": "^3.x.x",
    "js-file-download": "^0.4.1",
    "js-yaml": "^3.13.1",
    "lodash": "^4.17.19",
    "memoizee": "^0.4.12",
    "prop-types": "^15.7.2",
    "randombytes": "^2.1.0",
    "react": "^15.6.2",
    "react-copy-to-clipboard": "5.0.1",
    "react-debounce-input": "^3.2.0",
    "react-dom": "^15.6.2",
    "react-immutable-proptypes": "2.1.0",
    "react-immutable-pure-component": "^1.1.1",
    "react-inspector": "^2.3.0",
    "react-motion": "^0.5.2",
    "react-redux": "=4.4.10",
    "react-syntax-highlighter": "=13.5.0",
    "redux": "=3.7.2",
    "redux-immutable": "3.1.0",
    "remarkable": "^2.0.1",
    "reselect": "^4.0.0",
    "serialize-error": "^2.1.0",
    "sha.js": "^2.4.11",
    "swagger-client": "=3.11.0",
    "url-parse": "^1.4.7",
    "xml-but-prettier": "^1.0.1",
    "zenscroll": "^4.0.2"
  },
  "devDependencies": {
    "@babel/cli": "^7.10.1",
    "@babel/core": "^7.10.2",
    "@babel/plugin-proposal-class-properties": "^7.10.1",
    "@babel/plugin-proposal-nullish-coalescing-operator": "^7.10.1",
    "@babel/plugin-proposal-optional-chaining": "^7.10.1",
    "@babel/plugin-transform-runtime": "^7.10.1",
    "@babel/preset-env": "^7.10.2",
    "@babel/preset-react": "^7.10.1",
    "@babel/register": "^7.10.1",
    "@jest/globals": "=26.4.2",
    "@release-it/conventional-changelog": "=1.1.4",
    "autoprefixer": "^9.0.0",
    "babel-eslint": "^10.0.0",
    "babel-loader": "^8.1.0",
    "babel-plugin-lodash": "=3.3.4",
    "babel-plugin-module-resolver": "^4.0.0",
    "babel-plugin-transform-react-remove-prop-types": "^0.4.13",
    "body-parser": "^1.19.0",
    "bundlesize": "^0.18.0",
    "chromedriver": "^85.0.0",
    "copy-webpack-plugin": "^6.0.0",
    "cors": "^2.8.5",
    "cross-env": "=7.0.2",
    "css-loader": "^4.0.0",
    "cssnano": "=4.1.10",
    "cypress": "=5.2.0",
    "dedent": "^0.7.0",
    "deepmerge": "^4.0.0",
    "enzyme": "^2.7.1",
    "eslint": "^4.1.1",
    "eslint-plugin-import": "^2.21.1",
    "eslint-plugin-jest": "=24.0.1",
    "eslint-plugin-mocha": "^8.0.0",
    "eslint-plugin-react": "^7.20.0",
    "esm": "=3.2.25",
    "expect": "^1.20.2",
    "express": "^4.17.1",
    "file-loader": "^6.0.0",
    "git-describe": "^4.0.4",
    "http-server": "^0.12.3",
    "ignore-assets-webpack-plugin": "^2.0.1",
    "inspectpack": "=4.5.2",
    "jest": "=25.5.4",
    "jsdom": "=15.2.1",
    "json-loader": "^0.5.7",
    "json-merger": "^1.1.2",
    "json-server": "^0.15.0",
    "less": "^3.11.2",
    "license-checker": "^25.0.0",
    "mini-css-extract-plugin": "^0.11.0",
    "mocha": "=7.2.0",
    "nightwatch": "^1.3.6",
    "node-sass": "^4.14.1",
    "npm-audit-ci-wrapper": "^3.0.0",
    "npm-run-all": "^4.1.5",
    "oauth2-server": "^2.4.1",
    "open": "^7.0.4",
    "postcss-loader": "^3.0.0",
    "postcss-preset-env": "=6.7.0",
    "prettier": "^2.0.0",
    "raw-loader": "^4.0.0",
    "react-test-renderer": "^15.5.4",
    "release-it": "=13.6.5",
    "rimraf": "^3.0.0",
    "sass-loader": "^7.1.0",
    "selenium-server-standalone-jar": "^3.141.5",
    "source-map-support": "^0.5.19",
    "standard": "^11.0.1",
    "tachyons-sass": "^4.9.5",
    "terser-webpack-plugin": "^4.0.0",
    "url-loader": "^2.3.0",
    "webpack": "^4.43.0",
    "webpack-bundle-size-analyzer": "^3.1.0",
    "webpack-cli": "^3.3.11",
    "webpack-dev-server": "^3.11.0",
    "webpack-stats-plugin": "=0.3.2"
  },
  "config": {
    "deps_check_dir": ".deps_check"
  },
  "bundlesize": [
    {
      "path": "./dist/swagger-ui-bundle.js",
      "maxSize": "1 MB",
      "compression": "none"
    }
  ],
  "description": "[![NPM version](https://badge.fury.io/js/swagger-ui.svg)](http://badge.fury.io/js/swagger-ui) [![Build Status](https://jenkins.swagger.io/view/OSS%20-%20JavaScript/job/oss-swagger-ui-master/badge/icon?subject=jenkins%20build)](https://jenkins.swagger.io/view/OSS%20-%20JavaScript/job/oss-swagger-ui-master/) [![npm audit](https://jenkins.swagger.io/buildStatus/icon?job=oss-swagger-ui-security-audit&subject=npm%20audit)](https://jenkins.swagger.io/job/oss-swagger-ui-security-audit/lastBuild/console) ![total GitHub contributors](https://img.shields.io/github/contributors-anon/swagger-api/swagger-ui.svg)",
  "bugs": {
    "url": "https://github.com/swagger-api/swagger-ui/issues"
  },
  "directories": {
    "doc": "docs",
    "test": "test"
  },
  "author": ""
}


Is this OK? (yes)

安装 express 

npm install express --save

创建 public 目录

创建 public 目录, 并将 swagger-ui/dist 复制到 public 目录

mkdir public
cp -r dist/ public/

创建 index.js 文件

创建 index.js 文件, 监听端口 3000

vim index.js

内容如下

var express = require('express');
var app = express();
var http = require('http');
app.use('/static', express.static('public'));
app.get('/', function (req, res) {
  res.send('Hello World!');
});

app.listen(3000, function () {
  console.log('Example app listening on port 3000!');
});

启动服务 

node index.js

访问地址: http://127.0.0.1:3000/static/index.html

后台启动进程

为了使进程在后台运行, 可以使用 nohup 命令

# 后台启动 Swagger Editor 服务
nohup http-server -p 8081 swagger-editor-3.14.0 &

# 查询进程
ps aux | grep http-server

# 根据端口号查询进程
lsof -i:8081

# 杀掉进程
kill -9 xxxxx

至此, Swagger Editor 和 Swagger UI 环境搭建完成, 你可以通过浏览器访问和使用这些工具来管理 API 文档, Perfect!

原文

centos 7 搭建 Swagger Editor + Swagger-UI
CentOS 7 搭建swagger Api文档管理系统

最后更新于 2020-09-19
Copyright © 2016 - 2025 AceSheep Blog
使用 Hugo 构建
主题 Stack 由 Jimmy 设计