Swagger在Ubuntu中的使用教程

一、准备工作：安装Node.js和npm

Swagger的大部分工具（如Swagger Editor、Swagger UI）依赖Node.js环境，因此首先需要安装Node.js和npm（Node.js的包管理器）。
打开终端，运行以下命令更新系统包列表并安装Node.js（版本≥14.x）及npm：

sudo apt update
sudo apt install -y nodejs npm

安装完成后，验证安装是否成功：

node -v  # 查看Node.js版本
npm -v   # 查看npm版本

若输出版本号，则说明安装成功。

二、安装Swagger工具

1. 安装Swagger UI（可视化API文档）

Swagger UI是用于展示和测试API文档的工具，以下是两种常用安装方式：

方式一：通过npm全局安装（推荐）

sudo npm install -g swagger-ui-express

方式二：通过Docker安装（快速部署）

若系统已安装Docker，可直接拉取Swagger UI镜像并运行：

sudo apt install -y docker.io  # 若未安装Docker
docker pull swaggerapi/swagger-ui-express

Docker方式无需手动配置，更轻量便捷。

三、配置Swagger UI

1. 准备Swagger规范文件

Swagger UI需要swagger.yaml或swagger.json文件来定义API结构。以下是一个简单的swagger.yaml示例：

swagger: '2.0'
info:
  title: Sample API
  description: A demo API for Swagger integration
  version: 1.0.0
host: localhost:3000
basePath: /api
schemes:
  - http
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string

将上述内容保存为swagger.yaml（或swagger.json），放在项目根目录下。

2. 启动Swagger UI服务

若使用npm安装：

创建一个Express项目并集成Swagger UI：

mkdir swagger-ui-demo && cd swagger-ui-demo
npm init -y
npm install express swagger-ui-express yamljs

创建server.js文件，内容如下：

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

// 加载swagger.yaml文件
const swaggerDocument = YAML.load('./swagger.yaml');

const app = express();
// 将Swagger文档挂载到/api-docs路径
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Swagger UI is running at http://localhost:${PORT}/api-docs`);
});

运行服务：

node server.js

若使用Docker安装：

docker run -p 8080:8080 -v $(pwd):/app -e SWAGGER_JSON=/app/swagger.yaml swaggerapi/swagger-ui-express

访问Swagger UI：

npm方式：浏览器打开http://localhost:3000/api-docs
Docker方式：浏览器打开http://localhost:8080
即可看到Swagger UI界面，点击“Explore”即可查看和测试API。

四、使用Swagger Editor（设计API规范）

Swagger Editor是在线编辑Swagger规范的工具，支持实时语法检查和预览。

1. 安装Swagger Editor

方式一：通过npm全局安装

sudo npm install -g swagger-editor

方式二：下载并解压

wget https://github.com/swagger-api/swagger-editor/archive/refs/tags/v3.48.0.tar.gz
tar -xvf v3.48.0.tar.gz
cd swagger-editor-3.48.0
npm install
npm install -g http-server

2. 启动Swagger Editor

http-server -p 8080

访问Swagger Editor：浏览器打开http://localhost:8080，点击“File”→“Import File”选择本地的swagger.yaml文件，即可在线编辑和预览API文档。

五、集成Swagger到Spring Boot项目（可选）

若项目基于Spring Boot，可通过以下步骤集成Swagger：

1. 添加依赖

在pom.xml中添加Springfox Swagger2和Swagger UI依赖：

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.9.2</version>
</dependency>

2. 配置Swagger

创建配置类SwaggerConfig.java：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
      .select()
      .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) // 替换为你的Controller包路径
      .paths(PathSelectors.any())
      .build();
  }
}

3. 运行项目并访问

启动Spring Boot应用，浏览器访问http://localhost:8080/swagger-ui.html，即可看到生成的API文档。

六、常见问题解决

问题1：swagger-ui-express未找到：确保已正确安装swagger-ui-express（npm install swagger-ui-express），且版本兼容。
问题2：无法访问Swagger UI：检查防火墙是否开放端口（如3000、8080），或使用curl http://localhost:3000/api-docs测试服务是否正常运行。
问题3：Swagger Editor无法加载本地文件：确保swagger.yaml文件路径正确，或在Docker方式中通过-v参数挂载文件目录。

通过以上步骤，你可以在Ubuntu上完成Swagger的安装、配置及使用，实现API文档的可视化管理和测试。

swagger在ubuntu中的使用教程