如何在Ubuntu上使用Swagger生成API文档
在Ubuntu系统上，Swagger（现多为OpenAPI规范）可通过Node.js工具链或**编程框架（如Spring Boot）**生成API文档。以下是两种常见场景的具体步骤：
首先确保系统已安装Node.js和npm（Node.js包管理器），用于安装Swagger相关工具：
sudo apt update
sudo apt install -y nodejs npm
验证安装：
node -v # 查看Node.js版本
npm -v # 查看npm版本
通过npm全局安装Swagger UI Express（用于托管文档）和Swagger-jsdoc（用于从代码注释生成文档）：
sudo npm install -g swagger-ui-express swagger-jsdoc
创建swagger.yaml文件（推荐YAML格式，更易读），定义API元数据、路径、参数及响应：
openapi: 3.0.0
info:
title: Sample API
description: A simple API for demonstration
version: 1.0.0
servers:
- url: http://localhost:3000
description: Local development server
paths:
/users:
get:
summary: Get all users
description: Retrieve a list of all registered users
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: integer
format: int64
description: Unique user ID
name:
type: string
description: User's full name
创建一个简单的Express应用，集成Swagger UI以可视化文档：
// server.js
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const yaml = require('yamljs');
// 加载Swagger文档
const swaggerDocument = yaml.load('./swagger.yaml');
const app = express();
const PORT = 3000;
// 托管Swagger UI
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
app.listen(PORT, () => {
console.log(`Server running at http://localhost:${PORT}`);
console.log(`Swagger UI available at http://localhost:${PORT}/api-docs`);
});
启动Express应用：
node server.js
打开浏览器访问http://localhost:3000/api-docs，即可看到交互式的Swagger UI界面，包含API的所有路径、参数及示例。
若项目使用Spring Boot，可通过Swagger注解自动生成文档，步骤如下：
在pom.xml（Maven）中添加Swagger核心依赖和UI依赖：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
创建配置类SwaggerConfig.java，指定扫描的Controller包路径：
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.example.demo.controller")) // 替换为你的Controller包路径
.paths(PathSelectors.any())
.build();
}
}
在Controller类和方法上添加Swagger注解，描述接口功能、参数及响应：
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;
@RestController
@RequestMapping("/api/users")
@Api(tags = "User Management", description = "Operations related to user management")
public class UserController {
@GetMapping
@ApiOperation(value = "Get all users", notes = "Retrieve a list of all registered users")
public List<String> getAllUsers() {
List<String> users = new ArrayList<>();
users.add("John Doe");
users.add("Jane Smith");
return users;
}
@GetMapping("/{id}")
@ApiOperation(value = "Get user by ID", notes = "Retrieve a user by their unique ID")
public String getUserById(
@ApiParam(value = "User ID", required = true, example = "1")
@PathVariable Long id) {
return "User " + id;
}
}
启动Spring Boot应用，访问http://localhost:8080/swagger-ui/index.html（端口可能因配置不同而变化），即可看到自动生成的API文档，包含接口描述、参数说明及测试界面。
@ApiOperation、@ApiParam）详细描述接口，提升文档可读性。以上步骤覆盖了Ubuntu环境下Swagger生成API文档的主要场景，可根据项目技术栈选择合适的方式。
