ubuntu swagger如何配置认证

5月 7th, 2025

在Ubuntu上配置Swagger（现在通常指的是OpenAPI Generator或Swagger UI）的认证，通常涉及到几个步骤。以下是一个基本的指南，以帮助你在Ubuntu系统上配置Swagger UI的认证：

1. 安装必要的软件

首先，确保你的Ubuntu系统上已经安装了以下软件：

Node.js 和 npm：Swagger UI通常通过Node.js运行。
OpenAPI Generator：如果你打算从OpenAPI规范生成代码，这个工具非常有用。

你可以使用以下命令安装Node.js和npm：

sudo apt update
sudo apt install nodejs npm

对于OpenAPI Generator，你可以使用npm来安装：

sudo npm install -g @openapitools/openapi-generator-cli

2. 配置Swagger UI

方法一：使用Docker

如果你不想在本地系统上安装太多东西，可以使用Docker来运行Swagger UI。

拉取Swagger UI Docker镜像：

docker pull swaggerapi/swagger-ui-express

运行Swagger UI容器：

docker run -p 8080:8080 -e SWAGGER_JSON=/app/swagger.json -v /path/to/swagger.json:/app/swagger.json swaggerapi/swagger-ui-express

在这里，/path/to/swagger.json 是你的Swagger JSON文件的路径。

方法二：本地安装

如果你想在本地系统上安装Swagger UI，可以按照以下步骤操作：

克隆Swagger UI仓库：

git clone https://github.com/swagger-api/swagger-ui-express.git
cd swagger-ui-express

安装依赖：

npm install

创建一个简单的Express服务器：

在项目根目录下创建一个名为 server.js 的文件，并添加以下内容：

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

const swaggerDocument = YAML.load('./path/to/swagger.json');

const app = express();

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

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

在这里，./path/to/swagger.json 是你的Swagger JSON文件的路径。

运行服务器：

node server.js

3. 配置认证

基本认证

在Swagger JSON文件中，你可以添加基本认证信息：

{
  "openapi": "3.0.0",
  "info": {
    "title": "Example API",
    "version": "1.0.0"
  },
  "components": {
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "paths": {
    "/endpoint": {
      "get": {
        "summary": "An example endpoint",
        "security": [
          {
            "basicAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response"
          }
        }
      }
    }
  }
}

OAuth2

如果你需要更复杂的认证，比如OAuth2，可以在Swagger JSON文件中添加OAuth2配置：

{
  "openapi": "3.0.0",
  "info": {
    "title": "Example API",
    "version": "1.0.0"
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "password": {
            "tokenUrl": "https://example.com/oauth/token",
            "scopes": {
              "read": "Read access to the resource",
              "write": "Write access to the resource"
            }
          }
        }
      }
    }
  },
  "paths": {
    "/endpoint": {
      "get": {
        "summary": "An example endpoint",
        "security": [
          {
            "oauth2": ["read"]
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response"
          }
        }
      }
    }
  }
}