linux

Linux Swagger使用指南:如何快速上手

小樊
99
2025-02-15 10:32:38
栏目: 智能运维

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

1. 安装Swagger

安装Swagger UI

  1. 更新包列表

    sudo apt update
    
  2. 安装必要的依赖

    sudo apt install -y openjdk-11-jre-headless
    
  3. 下载并解压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
    
  4. 移动解压后的文件到Web服务目录(例如 /var/www/html):

    sudo mv springfox-swagger-ui-2.9.2 /var/www/html/swagger-ui
    
  5. 配置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>
    
  6. 启动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 块中的 rootindex 指令:

      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

  1. 下载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
    
  2. 移动文件到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
    
  3. 创建一个简单的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>
    
  4. 启动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 块中的 rootindex 指令:

      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

  1. 添加依赖: 在项目的 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>
    
  2. 配置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();
      }
    }
    
  3. 启动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
看了该问题的人还看了