117笔记问答Swagger（现更名为OpenAPI Specification）是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。通过Swagger，开发者可以显著提高Linux服务器API的可读性和易用性。以下是一些具体步骤和方法：
1. 安装和配置Swagger
安装Swagger Editor和Swagger UI
- Swagger Editor：一个强大的编辑器，允许用户手动编写OpenAPI定义（YAML或JSON格式），并检查语法错误。它集成了Swagger Codegen，可以用于生成服务器代码和客户端SDK。
- Swagger UI：一个文档渲染器，可以展示OpenAPI定义的API文档。用户可以通过UI直观地看到API的请求和响应参数、错误码、返回数据类型等信息，从而更容易理解和使用API。
在Linux服务器上安装Swagger Editor和Swagger UI的步骤如下：
# 安装Node.js和npm sudo apt update sudo apt install -y nodejs npm # 安装Express和其他必要的模块 sudo npm install -g express body-parser cookie-parser multer # 部署Swagger Editor docker pull swaggerapi/swagger-editor:v4.6.0 docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0 # 部署Swagger UI docker pull swaggerapi/swagger-ui:v4.15.5 docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5
配置Web服务器（可选）
- Nginx：
sudo apt install nginx sudo nano /etc/nginx/sites-available/default
在配置文件中添加以下内容：server { listen 80; server_name your_server_ip_or_domain; root /var/www/html; index index.html index.htm; location / { try_files $uri $uri/ /index.html; } } sudo systemctl restart nginx
2. 使用Swagger注解提高API文档质量
在您的API控制器和模型类中，使用OpenAPI注解来描述API和模型。例如：
import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RestController; @RestController @Api(tags = "用户管理") public class UserController { @GetMapping("/users/{id}") @ApiOperation(value = "https://www.yisu.com/ask/根据ID获取用户", notes = "返回指定ID的用户") public User getUserById(@ApiParam(value = "https://www.yisu.com/ask/要返回的用户ID", required = true) @PathVariable("id") Long id) { // 获取用户逻辑 return new User(id, "张三"); } } 3. 生成和查看API文档
使用Maven或Gradle构建项目时，OpenAPI会自动生成API文档。启动Spring Boot应用后，访问以下URL查看文档：
http://localhost:8080/swagger-ui/index.html
4. 在线测试API
Swagger UI提供交互式界面，允许您在浏览器中直接测试API。
5. 代码生成和Mock Server
使用Swagger Codegen从OpenAPI定义生成服务器代码和客户端SDK。虽然OpenAPI本身不提供Mock Server，但您可以结合其他工具（如WireMock）创建Mock数据。
java -jar swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l spring -o /path/to/output/directory
6. 安全性和访问控制
确保Swagger UI的安全性，例如通过配置认证和授权机制来保护敏感的API文档。这可以通过在Swagger配置中添加安全方案和定义安全要求来实现。
7. 文档生成和更新
通过维护OpenAPI定义文件（YAML或JSON格式），可以轻松地更新API文档。这样，所有相关人员都可以访问最新的API文档，提高了协作效率。
通过以上步骤，您可以在Linux环境下有效地提高Swagger API的可读性和可维护性，同时确保API的安全性。