CentOS Swagger使用教程有哪些

在CentOS系统上使用Swagger（通常指的是OpenAPI Specification，简称OAS）可以有效地设计和文档化RESTful API，提高API的可读性和可维护性。以下是一个基本的CentOS上使用Swagger的教程：

准备工作

1. 安装Node.js和npm：

sudo yum install -y gcc-c++ make
curl -sL https://rpm.nodesource.com/setup_14.x | sudo bash -
sudo yum install -y nodejs

验证安装是否成功：

node -v
npm -v

2. 安装Swagger Editor和Swagger UI：

• 安装Swagger Editor：

mkdir /opt/swagger
cd /opt/swagger
wget https://github.com/swagger-api/swagger-editor/archive/v3.14.0.tar.gz
tar -xzf v3.14.0.tar.gz
cd swagger-editor-3.14.0
npm install -g http-server
http-server -p 8080

访问 http://:8080 确认可以访问。

• 安装Swagger UI：

cd /opt/swagger
wget https://github.com/swagger-api/swagger-ui/archive/v3.34.0.tar.gz
tar -xzf v3.34.0.tar.gz
cd swagger-ui-3.34.0
npm install express --save
mkdir public
cp -r swagger-ui-3.34.0/dist/* public/

创建并修改 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!'); });

启动 index.js 文件：

node index.js

访问 http://:3000 确认可以访问。

配置Swagger

在你的Node.js应用中，你需要配置Swagger以生成API文档。以下是一个基本的配置示例：

const express = require('express');
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerui = require('swagger-ui-express');

const swaggerdefinition = {
  openapi: '3.0.0',
  info: {
    title: 'My API Documentation',
    version: '1.0.0',
    description: 'This is my API documentation',
  },
  servers: [{ url: 'http://localhost:3000', description: 'Development server' }],
};

const options = {
  swaggerdefinition,
  apis: ['./routes/*.js'], // 指向API文档的路径
};

const swaggerspec = swaggerJsdoc(options);

app.use('/api-docs', swaggerui.serve, swaggerui.setup(swaggerspec));

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

编写Swagger注释

在你的路由文件或控制器文件中，添加Swagger注释以描述API。例如：

/**
 * @swagger
 * /users:
 *   get:
 *     tags: [users]
 *     summary: Get user list
 *     description: Returns a list of all users
 *     responses:
 *       200:
 *         description: Request successful
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/User'
 */

生成和查看API文档

启动你的Node.js应用后，通过访问 http://localhost:3000/api-docs 来查看Swagger UI。在这里，你可以测试API的各个端点，并查看详细的API文档。

使用Swagger注解

为了更好地描述API，你可以使用Swagger提供的注解。以下是一些常用的注解示例：

/**
 * @swagger
 * /users:
 *   get:
 *     tags: [users]
 *     summary: Get user list
 *     responses:
 *       200:
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 */

通过以上步骤，你可以在CentOS上成功安装和配置Swagger，并生成和查看API文档。这将有助于你更好地设计和文档化RESTful API，提高API的可读性和可维护性。