如何利用Swagger在Linux上进行API接口文档共享 - 问答

1. 准备Linux环境基础依赖
在Linux系统上，首先需要安装Node.js（用于运行Swagger Editor/UI）、npm（Node.js包管理器）及Java环境（若使用Spring Boot集成Swagger）。

安装Node.js和npm：通过包管理器安装稳定版本（如Ubuntu/Debian使用apt）：
```
sudo apt update
sudo apt install -y nodejs npm
```
验证安装：node -v（显示版本号）、npm -v（显示版本号）。
安装Java环境（可选，用于Spring Boot项目）：若需集成Spring Boot，安装OpenJDK 11+：
```
sudo apt install -y openjdk-11-jdk
```

2. 部署Swagger Editor（在线编写API定义）
Swagger Editor是可视化编辑OpenAPI规范的工具，可通过以下两种方式部署：

方式一：npm全局安装+启动
```
sudo npm install -g swagger-editor
nohup swagger-editor &
```
访问http://your_server_ip:8080即可使用（默认端口8080）。
方式二：Docker容器化部署（推荐）
拉取官方镜像并映射端口：
```
docker pull swaggerapi/swagger-editor:v4.6.0
docker run -d -p 38080:8080 --name swagger-editor swaggerapi/swagger-editor:v4.6.0
```
访问http://your_server_ip:38080即可在线编辑API文档。

3. 部署Swagger UI（渲染API文档）
Swagger UI是将OpenAPI规范（YAML/JSON）渲染为可视化界面的工具，部署方式如下：

方式一：npm构建+静态文件托管
```
sudo npm install -g swagger-ui
mkdir -p /var/www/swagger-ui
swagger-ui --output /var/www/swagger-ui
```
配置Nginx/Apache托管/var/www/swagger-ui目录，访问http://your_server_ip/swagger-ui查看文档。
方式二：Docker容器化部署（推荐）
拉取官方镜像并映射端口：
```
docker pull swaggerapi/swagger-ui:v4.15.5
docker run -d -p 38081:8080 --name swagger-ui -e SWAGGER_FILE=/app/swagger.yaml swaggerapi/swagger-ui:v4.15.5
```
将API定义文件（swagger.yaml）挂载至容器/app目录，访问http://your_server_ip:38081即可查看渲染后的文档。

4. 配置API定义文件
API定义是Swagger共享的核心，需创建swagger.yaml（或swagger.json）文件，描述接口的路径、参数、响应等。示例如下：

swagger: '2.0'
info:
  title: Sample API
  version: 1.0.0
  description: A demo API for documentation sharing
basePath: /api/v1
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
    required:
      - id
      - name

将swagger.yaml放置在Swagger UI可访问的目录（如Docker挂载的/app目录或Nginx的静态资源目录）。

5. 集成到应用（可选，自动生成文档）
若使用Spring Boot开发API，可通过集成Swagger自动生成文档：

添加依赖（Maven示例）：

<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>

配置Swagger：创建配置类启用Swagger：

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.any())
                .paths(PathSelectors.any())
                .build();
    }
}

访问文档：启动Spring Boot应用，访问http://your_server_ip:8080/swagger-ui.html查看自动生成的文档。

6. 实现安全访问（可选，保护文档）
为防止未授权访问，可通过以下方式保护Swagger文档：

密码保护（Nginx示例）：配置Nginx Basic Auth：

sudo apt install -y apache2-utils
sudo htpasswd -c /etc/nginx/.htpasswd admin  # 设置用户名admin和密码

修改Nginx配置，添加认证：

server {
    listen 80;
    server_name your_server_ip;
    location /swagger-ui {
        auth_basic "Restricted Access";
        auth_basic_user_file /etc/nginx/.htpasswd;
        proxy_pass http://localhost:38081;
    }
}

Docker容器权限控制：限制容器端口仅允许特定IP访问：
```
docker run -d -p 127.0.0.1:38081:8080 swaggerapi/swagger-ui:v4.15.5
```

7. 远程访问（可选，内网穿透）
若需从外部网络访问，可使用Cpolar等内网穿透工具：

安装Cpolar：

curl -L https://www.cpolar.com/static/downloads/install-release-cpolar.sh | sudo bash
sudo systemctl enable cpolar
sudo systemctl start cpolar

配置公网隧道：通过Cpolar管理界面创建HTTP隧道，指向Swagger UI的端口（如38081），获取公网地址（如https://your-subdomain.cpolar.io），即可通过该地址远程访问文档。

0 赞

0 踩