Swagger文档在Debian的生成方法-linux运维-PHP中文网

Swagger文档在Debian的生成方法

月夜之吻

发布： 2025-06-13 09:26:33

原创

352人浏览过

在debian系统上生成openapi规范（曾被称为swagger）文档，通常会结合spring boot框架进行开发与接口文档化。以下是完整的操作流程：

安装Java和Maven：确保你的Debian系统中已安装Java和Maven。如果尚未安装，可以使用以下命令进行安装：
```
<code> sudo apt update
 sudo apt install openjdk-11-jdk maven</code>
```
登录后复制
创建Spring Boot项目：使用Spring Initializr来生成一个新的Spring Boot项目。选择你需要的依赖项（例如Spring Web），然后下载项目压缩包。
解压并导入IDE：将下载的项目解压至本地目录，并通过你常用的开发工具（如IntelliJ IDEA或Eclipse）导入该项目。

添加Swagger依赖：打开项目的pom.xml文件，并加入以下Swagger相关的依赖配置：

<code> <dependencies><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></dependencies></code>

登录后复制

请根据当前使用的Spring Boot版本适当调整版本号，以确保兼容性。

配置Swagger功能：创建一个用于启用和配置Swagger的类文件。在src/main/java/com/yourpackage路径下新建名为SwaggerConfig.java的配置类：

<code> package com.yourpackage;

 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.basePackage("com.yourpackage")) // 修改为你自己的Controller所在包路径
                 .paths(PathSelectors.any())
                 .build();
     }
 }</code>

登录后复制

启动Spring Boot应用：在IDE内运行该Spring Boot程序，或者通过终端执行如下Maven命令启动：

Calliper 文档对比神器
文档内容对比神器

28

查看详情
```
<code> mvn spring-boot:run</code>
```
登录后复制
访问Swagger UI界面：应用启动完成后，在浏览器输入以下地址访问Swagger UI页面：
```
<code> http://localhost:8080/swagger-ui.html</code>
```
登录后复制
此时你应该能看到展示所有API信息的图形化界面。

添加API描述注解：在控制器类中引入适当的Swagger注解，从而增强接口说明。示例代码如下：

<code> package com.yourpackage.controller;

 import io.swagger.annotations.Api;
 import io.swagger.annotations.ApiOperation;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;

 @RestController
 @RequestMapping("/api")
 @Api(tags = "示例控制器")
 public class ExampleController {

     @GetMapping("/hello")
     @ApiOperation(value = "返回Hello World", notes = "根据用户ID获取用户信息")
     public String sayHello() {
         return "Hello, World!";
     }
 }</code>

登录后复制