Linux系统中Swagger API文档如何共享

在Linux系统中，Swagger API文档的共享可以通过以下几种方式进行：

1. 使用Swagger Editor和Swagger UI：

• Swagger Editor：是一个编辑器，可以在其中手动编写OpenAPI定义，或加载/粘贴任意OpenAPI定义以检查它们是否存在语法错误。Swagger Editor 还集成了 Swagger Codegen。
• Swagger UI：是一个文档渲染器，是一个 HTML 页面。可以把它指向一个 OpenAPI 的定义（YAML或JSON文件）。

你可以通过将Swagger Editor和Swagger UI部署在Linux服务器上，然后通过URL访问这些服务来共享API文档。例如，使用Docker容器化部署：

# 拉取swagger editor镜像
docker pull swaggerapi/swagger-editor:v4.6.0
# 运行swagger editor容器
docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0

# 拉取swagger UI镜像
docker pull swaggerapi/swagger-ui:v4.15.5
# 运行swagger UI容器
docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5

部署完成后，可以通过浏览器访问 http://<your-server-ip>:38080 来使用Swagger Editor，访问 http://<your-server-ip>:38081 来使用Swagger UI。

2. 密码保护与登录验证：

为了确保API文档的安全性，你可以为Swagger文档添加密码保护和登录验证。这可以通过在服务器端实现一个中间件来完成。例如，使用C#编写一个中间件来拦截请求并进行验证：

public class SwaggerAuthMiddleware
{
    private readonly RequestDelegate next;
    private readonly string userName = "admin";
    private readonly string password = "51aspx";
    public bool Flag = true;

    public SwaggerAuthMiddleware(RequestDelegate next)
    {
        this.next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        if (context.Request.Path.StartsWithSegments("/SignOut") && Flag == true)
        {
            context.Request.Headers.Remove("Authorization");
            context.Response.Headers["www-authenticate"] = "Basic";
            context.Response.Headers["Hello"] = "World";
            context.Response.StatusCode = (int)HttpStatusCode.Unauthorized;
            Flag = false;
            return;
        }

        Flag = true;
        string authHeader = context.Request.Headers["Authorization"];
        if (authHeader != null && authHeader.StartsWith("Basic"))
        {
            var header = AuthenticationHeaderValue.Parse(authHeader);
            var base64 = Convert.FromBase64String(header.Parameter);
            var credentials = Encoding.UTF8.GetString(base64).Split(':');
            var username = credentials[0];
            var password = credentials[1];
            if (username.Equals(userName) && password.Equals(password))
            {
                // 验证通过
                Flag = true;
            }
            else
            {
                // 验证失败
                context.Response.StatusCode = (int)HttpStatusCode.Unauthorized;
                return;
            }
        }
        else
        {
            // 验证失败
            context.Response.StatusCode = (int)HttpStatusCode.Unauthorized;
            return;
        }

        await next(context);
    }
}

在ASP.NET Core项目中，你可以将这个中间件添加到 Startup.cs 文件的 Configure 方法中：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseMiddleware<SwaggerAuthMiddleware>();
    // 其他中间件和路由配置
}

通过这种方式，只有提供正确用户名和密码的用户才能访问Swagger API文档。

3. 使用Swagger Codegen生成代码：

Swagger Codegen可以从OpenAPI定义生成服务器代码和客户端SDK。这样，你可以确保调用端代码、服务端代码以及接口文档的一致性。生成的代码可以部署到Linux服务器上，并通过API文档页面进行访问和共享。

例如，使用以下命令生成Java客户端代码：

java -jar swagger-codegen-cli-2.4.29.jar generate -i ./swagger.json -l java -o ./client

生成的代码可以包含API文档，并且可以通过特定的URL进行访问和共享。

通过以上方法，你可以在Linux系统中有效地共享和管理Swagger API文档，确保其安全性和一致性。

辰迅云「云服务器」，即开即用、新一代英特尔至强铂金CPU、三副本存储NVMe SSD云盘，价格低至29元/月。点击查看>>