Linux Swagger使用指南：如何快速上手 - 问答

在Linux系统上快速上手Swagger，通常涉及以下几个步骤：

1. 安装Swagger

安装Swagger UI

更新包列表：
```
sudo apt update
```

安装必要的依赖：

sudo apt install -y openjdk-11-jre-headless

下载并解压Swagger UI：

wget https://repo1.maven.org/maven2/io/springfox/springfox-swagger-ui/2.9.2/springfox-swagger-ui-2.9.2.html
unzip springfox-swagger-ui-2.9.2.html

移动解压后的文件到Web服务目录（例如 /var/www/html）：
```
sudo mv springfox-swagger-ui-2.9.2 /var/www/html/swagger-ui
```

配置Swagger UI：编辑 /var/www/html/swagger-ui/index.html 文件，找到以下行并进行修改：

<script>
  window.onload = function() {
    // Begin Swagger UI call region
    const ui = SwaggerUIBundle({
      url: "http://petstore.swagger.io/v2/api-docs",
      dom_id: '#swagger-ui',
      deepLinking: true,
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset
      ],
      plugins: [
        SwaggerUIBundle.plugins.DownloadUrl
      ],
      layout: "StandaloneLayout"
    });
    // End Swagger UI call region
    window.ui = ui;
  };
</script>

启动Web服务器（例如Apache或Nginx）：

Apache：

sudo a2ensite default.conf
sudo systemctl restart apache2

Nginx：

sudo cp /etc/nginx/sites-available/default /etc/nginx/sites-available/default.backup
sudo nano /etc/nginx/sites-available/default

修改 server 块中的 root 和 index 指令：

server {
  listen 80 default_server;
  listen [::]: 80 default_server;
  root /var/www/html;
  index index.html index.htm;
  server_name _;
  location / {
    try_files $uri $uri/ =404;
  }
}

保存并退出编辑器，然后重启Nginx：

sudo systemctl restart nginx

现在，你应该能够通过浏览器访问 http://your_server_ip/swagger-ui 来查看Swagger UI。

安装Swagger Editor

下载Swagger Editor：

wget https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.50.0/swagger-editor.min.js
wget https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.50.0/swagger-editor.min.css

移动文件到Web服务目录（例如 /var/www/html）：

sudo mv swagger-editor.min.js /var/www/html/swagger-editor.js
sudo mv swagger-editor.min.css /var/www/html/swagger-editor.css

创建一个简单的HTML文件来加载Swagger Editor：

sudo nano /var/www/html/swagger-editor.html

添加以下内容：

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" type="text/css" href="swagger-editor.css">
</head>
<body>
  <div id="swagger-editor"></div>
  <script src="swagger-editor.js"></script>
  <script>
    window.onload = function() {
      const editor = SwaggerEditor({
        url: "https://petstore.swagger.io/v2/api-docs",
        dom_id: '#swagger-editor'
      });
    };
  </script>
</body>
</html>

启动Web服务器（例如Apache或Nginx）：

Apache：

sudo a2ensite default.conf
sudo systemctl restart apache2

Nginx：

sudo cp /etc/nginx/sites-available/default /etc/nginx/sites-available/default.backup
sudo nano /etc/nginx/sites-available/default

修改 server 块中的 root 和 index 指令：

server {
  listen 80 default_server;
  listen [::]: 80 default_server;
  root /var/www/html;
  index index.html index.htm;
  server_name _;
  location / {
    try_files $uri $uri/ =404;
  }
}

保存并退出编辑器，然后重启Nginx：

sudo systemctl restart nginx

现在，你应该能够通过浏览器访问 http://your_server_ip/swagger-editor 来使用Swagger Editor。

2. 配置Swagger

在Spring Boot项目中集成Swagger

添加依赖：在项目的 pom.xml 文件中添加以下依赖：

<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>

配置Swagger：创建一个配置类来启用Swagger并定义一些基本信息：

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.yourproject")) // 这里写你的Controller包路径
        .paths(PathSelectors.any())
        .build();
  }
}

启动Spring Boot项目：启动Spring Boot项目后，访问 http://localhost:8080/swagger-ui.html（假设服务端口为8080），可以看到Swagger UI界面，其中展示了项目中定义的所有API接口及其详细信息。

3. 使用Swagger

使用注解描述API

使用Swagger提供的注解来描述API的详细信息，例如：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
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 {

  @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")
  @GetMapping("/users/{id}")
  public User getUser(@PathVariable Long id) {
    // ...
  }
}

在Swagger UI中测试API

启动Spring Boot项目后，访问 http://localhost:8080/swagger-ui.html，在Swagger UI界面中，你可以看到项目中定义的所有API接口及其详细信息，并可以直接在界面上测试接口。

4. 其他技巧

**版本控制

0 赞

0 踩