手记

一步一步学Swagger：新手入门指南

慕姐4208626
2024-11-15 14:00:07浏览 16
概述

Swagger 是一个流行的开放 API 标准和框架，用于描述、生成、调用和可视化 RESTful 风格的 Web 服务。它不仅提供了一套标准的接口定义语言（API Definition Language，简称 API 契约语言），还支持一系列与 API 相关的工具和服务。Swagger 在现代 Web 开发中扮演着极其重要的角色，能够自动生成文档、提供在线测试工具，并简化 API 调用和管理。

引入Swagger

什么是Swagger

Swagger 是一个流行的开放 API 标准和框架，用于描述、生成、调用和可视化 RESTful 风格的 Web 服务。它不仅提供了一套标准的接口定义语言（API Definition Language，简称 API 契约语言），还支持一系列与 API 相关的工具和服务。Swagger 的核心是一个用于描述 RESTful API 的开放标准，即 OpenAPI 规范。Swagger 使用 JSON 或 YAML 格式来定义 API，使得 API 的描述更加清晰和易于理解。

Swagger的作用和重要性

Swagger 在现代 Web 开发中扮演着极其重要的角色。它的主要作用和重要性包括：

  1. 文档自动生成：Swagger 可以自动生成 API 文档，将开发者从手动编写文档的繁琐工作中解放出来。这不仅节省了时间，还保证了文档的准确性和一致性。
  2. 在线测试工具：Swagger 提供了在线测试工具，可以让开发人员在开发过程中快速测试 API 接口的功能和性能，而无需离开浏览器。
  3. 提高团队协作效率：通过统一的 API 文档，前后端开发者可以更加高效地协作。前端可以根据 Swagger 文档直接调用 API，后端则可以专注于实现具体的业务逻辑。
  4. 简化 API 调用：Swagger 生成的文档通常包括 API 的输入参数、输出结果、状态码等详细信息，使得调用 API 更加直观和便捷。
  5. 促进 API 管理：Swagger 可以帮助开发者更好地管理 API，包括版本控制、权限管理等。

Swagger的使用场景

Swagger 主要适用于以下几种场景：

  1. API 设计与开发：在 API 设计阶段，Swagger 可以帮助开发者定义 API 的结构和行为；在开发阶段，Swagger 可以自动生成 API 文档，方便调试和测试。
  2. 前后端分离开发：在前后端分离的项目中，Swagger 可以作为前后端交互的桥梁，提高开发效率。
  3. 第三方服务集成：当集成第三方服务时，Swagger 提供的文档可以帮助开发者快速理解并调用这些服务。
  4. API 文档管理：在大型项目或团队合作中，Swagger 可以帮助统一 API 文档的标准和格式，便于管理和维护。

安装和配置Swagger

在项目中安装Swagger

在项目中使用 Swagger 需要先在开发环境中安装相应的库。以下是几种常见编程语言的安装步骤。

  1. Spring Boot 项目：

    • 首先，在 pom.xml 或 build.gradle 文件中添加 Swagger 的依赖。
    <!-- 在 pom.xml 中添加 Swagger 依赖 -->
<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>
    // 在 build.gradle 中添加 Swagger 依赖
implementation 'io.springfox:springfox-swagger2:2.9.2'
implementation 'io.springfox:springfox-swagger-ui:2.9.2'
    • 安装完成后，需要在 Application.java 或 SpringBootApplication.java 中配置 Swagger。
    package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

  2. Node.js 项目：

    • 在项目目录下运行以下命令安装 Swagger Node.js 库。
    npm install --save swagger-ui-express
    • 在 app.js 或 server.js 中加载 Swagger 并配置。
    const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

const app = express();

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

app.listen(3000, () => {
    console.log('Server running on port 3000');
});

  3. Django 项目：

    • 在 requirements.txt 中添加 Swagger 依赖。
    djangorestframework
drf-yasg
    • 然后在 views.py 或 urls.py 中配置 Swagger。
    from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi

schema_view = get_schema_view(
    openapi.Info(
        title="Django API Documentation",
        default_version='v1',
        description="API documentation for Django project",
        contact=openapi.Contact(email="admin@example.com"),
        license=openapi.License(name="MIT License"),
    ),
    public=True,
    permission_classes=[permissions.AllowAny],
)

urlpatterns = [
    path('api/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
]

  4. 配置Swagger的基本设置
    在完成安装后，需要对 Swagger 进行基本配置。不同的框架和库配置方式可能略有不同，以 Spring Boot 为例进行详细说明。

    1. 配置 Swagger 文档的基本信息：

      • 在 SwaggerConfig.java 或 SwaggerConfig.class 中配置 Swagger 文档的基本信息。
      package com.example.demo;

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.any())
                .paths(PathSelectors.any())
                .build();
    }
}

    2. 自定义 Swagger UI 显示的页面：

      • 可以通过配置文件或代码来自定义 Swagger UI 显示的页面，例如修改标题、描述、版本等信息。
      package com.example.demo;

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.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
                .pathMapping("/")
                .useDefaultResponseMessages(false);
    }

    private springfox.documentation.service.ApiInfo apiInfo() {
        return new springfox.documentation.service.ApiInfo(
                "Swagger API",
                "This is a Swagger API for the demo project.",
                "API TOS",
                "contact@domain.com",
                new springfox.documentation.service.Contact("", "", "contact@domain.com"),
                "MIT",
                "https://www.opensource.org/licenses/mit-license.php"
        );
    }
}

第一个Swagger API示例

创建简单的API文档

创建简单的 Swagger API 文档主要包括以下几个步骤：

  1. 定义 API 路径和请求类型：

    • 在 Spring Boot 项目中，使用 @RestController 和 @RequestMapping 注解来定义 API 路径及其请求类型。
    package com.example.demo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class HelloWorldController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello, World!";
    }
}

  2. 使用 Swagger 注解生成 API 文档：

    • 使用 @Api 注解来定义控制器类的描述信息，使用 @ApiOperation 注解来描述具体的方法。
    package com.example.demo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@RestController
@RequestMapping("/api")
@Api(value = "Hello World API", description = "API for HelloWorldController")
public class HelloWorldController {
    @GetMapping("/hello")
    @ApiOperation(value = "Return 'Hello, World!'", notes = "Returns a simple string")
    public String hello() {
        return "Hello, World!";
    }
}

  3. 使用Swagger注解进行API文档的生成
    使用 Swagger 注解可以自动生成 API 文档，以下是一些常用的 Swagger 注解：

    1. @Api：用于定义控制器类的描述信息。

      • 示例：
      package com.example.demo;

import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@RestController
@RequestMapping("/api")
@Api(value = "Hello World API", description = "API for HelloWorldController")
public class HelloWorldController {
}

    2. @ApiOperation：用于定义 API 方法的描述信息。

      • 示例：
      package com.example.demo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@RestController
@RequestMapping("/api")
@Api(value = "Hello World API", description = "API for HelloWorldController")
public class HelloWorldController {
    @GetMapping("/hello")
    @ApiOperation(value = "Return 'Hello, World!'", notes = "Returns a simple string")
    public String hello() {
        return "Hello, World!";
    }
}

    3. @ApiParam：用于描述方法参数。

      • 示例：
      package com.example.demo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import springfox.documentation.annotations.ApiIgnore;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@RestController
@RequestMapping("/api")
@Api(value = "Hello World API", description = "API for HelloWorldController")
public class HelloWorldController {
    @GetMapping("/hello")
    @ApiOperation(value = "Return 'Hello, ${name}!'", notes = "Returns a greeting")
    @ApiParam(value = "The name to greet", required = true)
    public String hello(@RequestParam(value = "name", required = true) String name) {
        return "Hello, " + name + "!";
    }
}

Swagger注解详解

@Api、@ApiOperation等常见注解的使用

Swagger 提供了一系列注解，用于说明 API 的各个部分。以下是一些常见的注解及其使用说明：

  1. @Api：用于定义控制器类的描述信息。

    • 示例：
    package com.example.demo;

import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@RestController
@RequestMapping("/api")
@Api(value = "Hello World API", description = "API for HelloWorldController")
public class HelloWorldController {
    @GetMapping("/hello")
    @ApiOperation(value = "Return 'Hello, ${name}!'", notes = "Returns a greeting")
    @ApiParam(value = "The name to greet", required = true)
    public String hello(@RequestParam(value = "name", required = true) String name) {
        return "Hello, " + name + "!";
    }
}

  2. @ApiOperation：用于定义 API 方法的描述信息。

    • 示例：
    package com.example.demo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@RestController
@RequestMapping("/api")
@Api(value = "Hello World API", description = "API for HelloWorldController")
public class HelloWorldController {
    @GetMapping("/hello")
    @ApiOperation(value = "Return 'Hello, ${name}!'", notes = "Returns a greeting")
    @ApiParam(value = "The name to greet", required = true)
    public String hello(@RequestParam(value = "name", required = true) String name) {
        return "Hello, " + name + "!";
    }
}

  3. @ApiParam：用于描述方法参数。

    • 示例：
    package com.example.demo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import springfox.documentation.annotations.ApiIgnore;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@RestController
@RequestMapping("/api")
@Api(value = "Hello World API", description = "API for HelloWorldController")
public class HelloWorldController {
    @GetMapping("/hello")
    @ApiOperation(value = "Return 'Hello, ${name}!'", notes = "Returns a greeting")
    @ApiParam(value = "The name to greet", required = true)
    public String hello(@RequestParam(value = "name", required = true) String name) {
        return "Hello, " + name + "!";
    }
}

  4. @ApiResponse：用于定义 API 方法可能返回的响应信息。

    • 示例：
    package com.example.demo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@RestController
@RequestMapping("/api")
@Api(value = "Hello World API", description = "API for HelloWorldController")
public class HelloWorldController {
    @GetMapping("/hello")
    @ApiOperation(value = "Return 'Hello, ${name}!'", notes = "Returns a greeting")
    @ApiParam(value = "The name to greet", required = true)
    @ApiResponse(code = 200, message = "Success", response = String.class)
    @ApiResponse(code = 400, message = "Bad request")
    public String hello(@RequestParam(value = "name", required = true) String name) {
        return "Hello, " + name + "!";
    }
}

  5. @ApiModel 和 @ApiModelProperty：用于定义模型和模型属性。

    • 示例：
    package com.example.demo;

import com.fasterxml.jackson.annotation.JsonProperty;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@RestController
@RequestMapping("/api")
@Api(value = "Hello World API", description = "API for HelloWorldController")
public class HelloWorldController {
    @GetMapping("/greet")
    @ApiOperation(value = "Return a greeting object", notes = "Returns a Greeting object")
    public Greeting greet() {
        return new Greeting("Hello, World!");
    }
}

class Greeting {
    @ApiModelProperty(value = "The message to greet", required = true)
    private String message;

    @ApiModelProperty(value = "The name of the person to greet", required = true)
    private String name;

    public Greeting(String message) {
        this.message = message;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

参数、返回值等注解的详细说明

以下是一些关于参数、返回值等注解的详细说明：

  1. 参数注解：

    • @ApiParam：用于描述方法参数。
    • @RequestParam、@PathVariable、@RequestBody 等 Spring MVC 注解通常与 @ApiParam 一起使用。
    package com.example.demo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import springfox.documentation.annotations.ApiIgnore;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@RestController
@RequestMapping("/api")
@Api(value = "Hello World API", description = "API for HelloWorldController")
public class HelloWorldController {
    @GetMapping("/hello")
    @ApiOperation(value = "Return 'Hello, ${name}!'", notes = "Returns a greeting")
    @ApiParam(value = "The name to greet", required = true)
    public String hello(@RequestParam(value = "name", required = true) String name) {
        return "Hello, " + name + "!";
    }
}

  2. 返回值注解：

    • @ApiResponse：用于定义 API 方法可能返回的响应信息。
    • @ApiModelProperty：用于定义模型属性。
    package com.example.demo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@RestController
@RequestMapping("/api")
@Api(value = "Hello World API", description = "API for HelloWorldController")
public class HelloWorldController {
    @GetMapping("/greet")
    @ApiOperation(value = "Return a greeting object", notes = "Returns a Greeting object")
    @ApiResponse(code = 200, message = "Success", response = Greeting.class)
    @ApiResponse(code = 400, message = "Bad request")
    public Greeting greet() {
        return new Greeting("Hello, World!");
    }
}

class Greeting {
    @ApiModelProperty(value = "The message to greet", required = true)
    private String message;

    public Greeting(String message) {
        this.message = message;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

测试API文档

使用Swagger UI测试API

一旦 Swagger API 文档生成完毕，可以通过 Swagger UI 来测试 API 接口。Swagger UI 是一个基于 HTML 和 JavaScript 实现的界面，允许用户通过浏览器界面直接调用 API，查看请求和响应的详细信息。

  1. 访问 Swagger UI：

    • 在开发环境下，启动项目后，访问 /swagger-ui.html 或 /swagger-ui 路径即可看到 Swagger UI 页面。
    package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}
    • 在浏览器中访问 http://localhost:8080/swagger-ui.html 或 http://localhost:8080/swagger-ui，即可看到 Swagger UI 页面。
  2. 测试 API 接口：
    • 在 Swagger UI 页面中，可以看到定义的所有 API 接口。
    • 选择一个接口，例如 GET /api/hello，在页面中可以看到接口的详细信息，包括请求参数、响应示例等。
    • 点击页面下方的 Try it out 按钮，输入必要的参数，点击 Execute 按钮即可发送请求并查看响应结果。

理解响应的各种状态码

在使用 Swagger UI 测试 API 时，需要理解 HTTP 状态码的意义。常见的 HTTP 状态码及其含义如下：

  • 200 OK：请求成功。
  • 201 Created：资源创建成功。
  • 204 No Content：请求成功，但响应中没有返回任何内容。
  • 400 Bad Request：请求格式错误，无法被服务器理解。
  • 401 Unauthorized：请求未授权，需要进行身份验证。
  • 403 Forbidden：服务器理解请求但拒绝执行。
  • 404 Not Found：请求的资源不存在。
  • 500 Internal Server Error：服务器遇到错误，无法完成请求。

常见问题与解决方法

新手常见问题

在使用 Swagger 的过程中，新手可能会遇到一些常见的问题：

  1. 无法访问 Swagger UI：
    • 通常是因为配置错误导致无法访问 Swagger UI 页面。需要检查项目配置是否正确，特别是在 SwaggerConfig 类中，确保配置信息正确。
  2. 缺少必要的依赖：
    • 如果项目中缺少必要的 Swagger 依赖，会导致无法正常使用 Swagger。确保在 pom.xml 或 build.gradle 文件中正确添加了 Swagger 的依赖。
  3. API 文档生成不完全：
    • 如果生成的 API 文档不完全，可能存在注解使用不正确或配置文件中的路径选择器设置不正确的情况。需要仔细检查注解和配置文件中的设置。
  4. 无法正确显示 API 路径：
    • 如果 API 路径显示不正确，可能是因为路径选择器设置错误。确保使用正确的 @RequestMapping 和 @GetMapping 等注解定义路径。
  5. 响应格式不正确：
    • 如果响应格式不正确，可能是因为返回的 Java 对象未正确定义或序列化。确保返回的 Java 对象定义了必要的属性和 getter/setter 方法。

解决方案与技巧

针对上述常见问题，提供了以下解决方案和技巧：

  1. 无法访问 Swagger UI：

    • 检查 SwaggerConfig 类中的配置信息，确保路径选择器和文档类型设置正确。例如：
    @Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

  2. 缺少必要的依赖：

    • 确保在项目的 pom.xml 或 build.gradle 文件中正确添加了 Swagger 的依赖。例如：
    <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>
    implementation 'io.springfox:springfox-swagger2:2.9.2'
implementation 'io.springfox:springfox-swagger-ui:2.9.2'

  3. API 文档生成不完全：

    • 检查注解的使用是否正确，并确保所有控制器类和方法都使用了 @Api 和 @ApiOperation 注解。例如：
    @RestController
@RequestMapping("/api")
@Api(value = "Hello World API", description = "API for HelloWorldController")
public class HelloWorldController {
    @GetMapping("/hello")
    @ApiOperation(value = "Return 'Hello, World!'", notes = "Returns a simple string")
    public String hello() {
        return "Hello, World!";
    }
}

  4. 无法正确显示 API 路径：

    • 确保使用 @RequestMapping 或 @GetMapping 等注解正确定义 API 路径。例如：
    @RestController
@RequestMapping("/api")
public class HelloWorldController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello, World!";
    }
}

  5. 响应格式不正确：

    • 确保返回的 Java 对象定义了必要的属性和 getter/setter 方法。例如：
    public class Greeting {
    private String message;

    public Greeting(String message) {
        this.message = message;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

通过以上步骤，可以有效地解决在使用 Swagger 过程中遇到的一些常见问题。如果遇到其他问题，建议参考官方文档或者在社区中寻求帮助。

相关标签
接口测试
API
0人推荐
随时随地看视频
慕课网APP