ubuntu里如何生成swagger文档

发布时间:2025-07-07 07:07:34

阅读量:36

在Ubuntu系统中生成Swagger文档，通常需要遵循以下步骤：

安装Swagger工具：你可以使用Swagger Codegen或者OpenAPI Generator来生成Swagger文档。这里以Swagger Codegen为例。

打开终端，运行以下命令来安装Swagger Codegen：
```
sudo apt-get update
sudo apt-get install -y java-11-openjdk-amd64
wget https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.21/swagger-codegen-cli-2.4.21.jar
sudo mv swagger-codegen-cli-2.4.21.jar /usr/local/bin/swagger
sudo chmod +x /usr/local/bin/swagger
```
注意：上面的命令安装的是Swagger Codegen的2.4.21版本，你可以在Swagger Codegen的官方GitHub页面查看最新版本并下载。
准备你的API定义： Swagger文档通常是基于OpenAPI规范编写的。你需要有一个.yaml或.json格式的OpenAPI规范文件。如果你还没有这个文件，你可以手动编写，或者使用Swagger Editor来创建和编辑。
生成Swagger文档：使用Swagger Codegen生成文档的命令如下：
```
swagger generate spec -i /path/to/your/api-definition.yaml -l 
```
其中/path/to/your/api-definition.yaml是你的OpenAPI规范文件的路径，是你想要生成的客户端代码的语言（例如：java, python, nodejs等）。

例如，如果你想要为Java生成客户端代码，命令将是：
```
swagger generate spec -i /path/to/your/api-definition.yaml -l java
```
这将在当前目录下生成一个名为api的文件夹，其中包含了Java客户端代码和相关的Swagger文档。
查看生成的Swagger UI： Swagger Codegen还提供了一个简单的Swagger UI，可以用来查看和测试你的API。要启动Swagger UI，运行以下命令：
```
java -jar /path/to/swagger-codegen-cli-2.4.21.jar generate server -i /path/to/your/api-definition.yaml -l spring-boot
```
这将生成一个Spring Boot项目，其中包含了Swagger UI。你可以使用以下命令来启动项目：
```
cd generated-project
./mvnw spring-boot:run
```
然后在浏览器中访问http://localhost:8080/swagger-ui.html来查看Swagger UI。