如何利用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），即可通过该地址远程访问文档。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！