linux

如何在Linux上使用Swagger UI展示API文档

小樊
35
2025-05-19 11:36:06
栏目: 智能运维

在Linux上使用Swagger UI展示API文档,可以按照以下步骤进行:

1. 安装Swagger UI

首先,你需要安装Swagger UI。你可以选择通过npm(Node.js的包管理器)来安装,或者直接下载预构建的版本。

通过npm安装

如果你还没有安装Node.js和npm,请先安装它们。然后运行以下命令来全局安装Swagger UI:

npm install -g swagger-ui-express

下载预构建版本

你也可以从Swagger UI的GitHub仓库下载预构建的版本:

wget https://github.com/swagger-api/swagger-ui/archive/master.zip
unzip master.zip
cd swagger-ui-master

2. 创建一个简单的Express应用

如果你选择通过npm安装Swagger UI,你可以创建一个简单的Express应用来托管Swagger UI。

安装Express

npm install express

创建Express应用

创建一个名为app.js的文件,并添加以下内容:

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');

// Load Swagger document
const swaggerDocument = YAML.load('./swagger.yaml');

const app = express();

// Serve Swagger docs
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

创建Swagger文档

创建一个名为swagger.yaml的文件,并添加你的API文档。例如:

swagger: '2.0'
info:
  title: Sample API
  description: A sample API to demonstrate Swagger UI
  version: '1.0.0'
host: localhost:3000
basePath: /
schemes:
  - http
paths:
  /users:
    get:
      summary: List all users
      responses:
        '200':
          description: An array of users
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string

3. 运行应用

在终端中运行你的Express应用:

node app.js

4. 访问Swagger UI

打开浏览器并访问http://localhost:3000/api-docs,你应该能够看到Swagger UI界面,并且可以浏览和测试你的API文档。

5. 使用Docker(可选)

如果你更喜欢使用Docker来部署Swagger UI,可以按照以下步骤进行:

创建Dockerfile

创建一个名为Dockerfile的文件,并添加以下内容:

FROM node:14

# Create app directory
WORKDIR /usr/src/app

# Install app dependencies
COPY package*.json ./
RUN npm install

# Bundle app source
COPY . .

EXPOSE 3000
CMD [ "node", "app.js" ]

构建Docker镜像

在终端中运行以下命令来构建Docker镜像:

docker build -t swagger-ui-app .

运行Docker容器

在终端中运行以下命令来启动Docker容器:

docker run -p 3000:3000 swagger-ui-app

现在,你可以访问http://localhost:3000/api-docs来查看Swagger UI界面。

通过以上步骤,你可以在Linux上成功使用Swagger UI展示API文档。

0
看了该问题的人还看了