当前位置：首页 > 文章列表 > 文章 > linux > Debian系统Swagger文档维护教程，超简单！

Debian系统Swagger文档维护教程，超简单！

2025-06-09 23:09:19 0浏览收藏

想要在Debian系统中轻松维护Swagger文档？本文为你提供超简单的解决方案！从添加Maven依赖、设置Swagger配置，到在Controller中整合Swagger注解，再到通过Swagger UI访问自动生成的文档界面，一步步教你快速上手。更重要的是，我们还提供了对Swagger文档实施密码保护及登录验证的详细步骤，以及升级Swagger UI和Swagger Editor的实用指南。无论你是新手还是老手，都能通过本文轻松掌握Debian系统下Swagger文档的维护与管理，让你的API文档更加清晰、安全、易用！

Debian系统中Swagger文档如何维护

在Debian系统中维护Swagger文档，可以参考以下步骤和建议：

添加依赖

假如你的项目采用Maven进行管理，那么在 pom.xml 文件中添加以下依赖：

io.springfoxspringfox-boot-starter3.0.0

设置Swagger配置

在Spring Boot项目的 application.yml 文件里，添加如下配置：

springfox:
  documentation:
    swagger-ui:
      enabled: true

在项目内整合Swagger

在Controller中运用注解：

package com.example.demo.controller;

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api")
@Api(tags = "Sample API")
public class SampleController {

    @GetMapping("/hello")
    @ApiOperation(value = "Returns a greeting message")
    public String sayHello() {
        return "Hello, World!";
    }
}

打开Swagger UI

启动项目后，打开浏览器，访问 http://localhost:8080/swagger-ui/，就可以看到Swagger自动生成的文档界面。

对Swagger文档实施密码保护及登录验证

创建一个中间件类：在项目根目录创建一个 SwaggerAuthMiddleware.cs 的类，用于实现访问API文档的登录验证与登出功能。

public class SwaggerAuthMiddleware {
    private readonly RequestDelegate _next;
    private readonly string _userName = "admin";
    private readonly string _password = "password";
    public bool _flag = true;

    public SwaggerAuthMiddleware(RequestDelegate next) {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context) {
        if (context.Request.Path.StartsWithSegments("/swagger-ui") && _flag) {
            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)) {
                return;
            }
        }
        context.Response.StatusCode = (int)HttpStatusCode.Unauthorized;
        await _next(context);
    }
}

配置中间件：在 Startup.cs 中配置中间件：

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

通过上述方法，你便能够在Debian系统上维护和管理Swagger文档，并保障其安全性。

升级Swagger版本

在Debian系统上升级Swagger（通常是Swagger UI或Swagger Editor），可按以下步骤操作：

升级Swagger UI：
- 若尚未安装Swagger UI，先安装：
```
 sudo apt updatesudo apt install nodejs npm
```
使用npm全局安装Swagger UI：
```
 sudo npm install -g swagger-ui-express
```
已经安装Swagger UI的话，可通过npm更新它：
```
 sudo npm update -g swagger-ui-express
```
若要安装指定版本的Swagger UI，可用以下命令：
```
 sudo npm install -g swagger-ui-express@version
```
将 version 替换为你所需的Swagger UI版本号。
升级Swagger Editor：
- 若未安装Swagger Editor，先安装：
```
 sudo apt updatesudo apt install nodejs npm
```
使用npm全局安装Swagger Editor：
```
 sudo npm install -g swagger-editor-cli
```
已经安装Swagger Editor的话，可通过npm更新它：
```
 sudo npm update -g swagger-editor-cli
```
如需安装特定版本的Swagger Editor，可用以下命令：
```
 sudo npm install -g swagger-editor-cli@version
```
将 version 替换为你需要的Swagger Editor版本号。