首页手记 Swagger学习：新手入门指南

Swagger学习：新手入门指南

标签：

接口测试 API

概述

本文详细介绍了如何进行Swagger学习，包括Swagger的基本概念、优势和应用场景。文章还涵盖了如何安装和配置Swagger，以及如何使用Swagger编写API文档和测试API。此外，还介绍了Swagger的高级功能和集成到项目中的方法。通过这些内容，读者可以全面了解并掌握Swagger的相关知识。

什么是Swagger

Swagger的定义和作用

Swagger是一个开源的规范和完整功能框架，用于描述、生成、调用和可视化RESTful风格的Web服务。它通过定义一组可重用的规范来描述API的操作、数据模型和交互方式，使得开发人员可以方便地生成和使用API文档。Swagger能够帮助开发者在实际开发过程中提高效率，确保不同团队之间的代码规范和接口一致性，同时也便于非技术人员理解和使用API。

Swagger的核心概念

Swagger的核心在于它定义了一套标准的API描述语言——OpenAPI规范（以前称为Swagger规范），该规范定义了描述HTTP RESTful API的标准JSON格式。通过定义这套规范，Swagger使得API的描述变得标准化、机器可读和易于理解。核心概念包括：

资源：在HTTP中，资源是指可由客户端访问的任何实体。资源可以是数据、服务或者其它资源的集合。每个资源都有一个URL（统一资源定位符），用来标识该资源。例如，一个用户资源可以通过/users/{userId}来访问。
操作：指对资源进行的操作，包括GET、POST、PUT、DELETE等HTTP方法。例如，GET操作用于获取资源，POST操作用于创建资源，PUT操作用于更新资源，DELETE操作用于删除资源。
参数：用于操作的输入和输出参数。参数可以分为路径参数、查询参数、请求体参数等。例如，/users/{userId}中的{userId}就是一个路径参数。
响应：每个操作都可能返回一个或多个响应，每个响应都有一个HTTP状态码和响应体。例如，GET操作可能返回HTTP 200状态码和用户信息作为响应体。

Swagger的优势和应用场景

Swagger的优势和应用场景包括但不限于以下几个方面：

易于维护：Swagger文档与API代码分离，文档的维护变得更加方便。
易于理解：Swagger文档采用结构化的描述方式，使得非技术人员也能快速理解API的功能。
测试工具：提供在线测试工具，方便开发者进行API的测试。
集成开发工具：Swagger集成在IDE工具中，如IntelliJ IDEA、Eclipse等，可以帮助开发者自动生成代码。
API发现：Swagger支持API注册表，开发者可以通过API注册表发现和使用API。
跨平台跨语言：Swagger支持多种编程语言和框架，包括Java、.NET、PHP、Node.js等。

示例项目

假设我们有一个简单的用户管理系统，包含用户注册、登录、获取用户信息等功能。我们可以通过Swagger来描述这些功能和API。

安装与配置Swagger

选择合适的Swagger版本

选择合适的Swagger版本对于项目的顺利进行至关重要。Swagger有两个主要版本：Swagger 1.x 和 OpenAPI 3.x。Swagger 1.x 是较老的版本，而 OpenAPI 3.x 是较新的版本，提供了更多功能和改进。选择版本时要根据项目的需求和兼容性来决定。如果项目需要与旧版Swagger兼容，可以选择Swagger 1.x；如果需要支持更丰富的功能和更好的兼容性，可以选择OpenAPI 3.x。

开发环境搭建

为了使用Swagger，您需要搭建一个支持Swagger的开发环境。以下是搭建环境的步骤：

安装Java环境：确保您的机器上安装了JDK 8或更高版本。
安装Maven：使用Maven作为构建工具来管理项目依赖。
安装IDE：推荐使用IntelliJ IDEA或Eclipse作为开发工具。
创建项目：使用Maven创建新的Java Web项目。
添加Swagger依赖：在项目的pom.xml文件中添加Swagger的依赖。

<dependencies>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.5.21</version>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-jaxrs</artifactId>
        <version>1.5.21</version>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-ui</artifactId>
        <version>3.29.0</version>
    </dependency>
</dependencies>
``

### 配置Swagger UI和文档
1. **配置Swagger资源文件**：在`src/main/resources`目录下创建一个`swagger.properties`文件，配置Swagger的基本信息，例如API的标题、版本等。

```properties
swagger.title=My API
swagger.description=My API Documentation
swagger.version=1.0.0
swagger.basePath=/api

配置Swagger UI：在项目的src/main/resources/static目录下创建一个swagger-ui文件夹，并将Swagger UI的静态资源文件复制到该目录下。Swagger UI的静态资源文件可以从Swagger的GitHub仓库或者官网下载得到。
配置Swagger配置类：创建一个Swagger配置类，配置Swagger的相关信息。

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.jaxrs.config.BeanConfig;
import io.swagger.jaxrs.listing.ApiListingResource;
import io.swagger.jaxrs.listing.SwaggerSerializers;
import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import javax.ws.rs.ext.Provider;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Provider
    public class SwaggerConfigInitializer implements ServletConfig {
        @Override
        public void init(ServletConfig servletConfig) throws ServletException {
            BeanConfig beanConfig = new BeanConfig();
            beanConfig.setTitle("My API");
            beanConfig.setDescription("My API Documentation");
            beanConfig.setVersion("1.0.0");
            beanConfig.setSchemes(new String[]{"http", "https"});
            beanConfig.setBasePath("/api");
            beanConfig.setHost("localhost:8080");
            beanConfig.setPrettyPrint(true);
            beanConfig.setProduces(new String[]{"application/json"});
            beanConfig.setResourcePackage("com.example.api");
            beanConfig.setScan(true);
        }
    }

    @Provider
    public class SwaggerConfigResourceConfig {
        @ApiOperation(value = "Swagger Configuration Resource")
        public void configure() {
            SwaggerSerializers.register();
        }
    }
}

配置Swagger UI路由：在Spring Boot的WebMvcConfigurer中配置Swagger UI的路由。

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class SwaggerUiConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
            .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

完成以上配置后，您的开发环境就已经准备好了，可以开始使用Swagger进行API文档的编写了。

示例项目

在上述配置完成后，我们可以通过创建一个简单的用户管理API来体验Swagger的使用。例如，创建一个用户API，包含用户注册、登录、获取用户信息等功能。

编写Swagger文档

使用Swagger编写API文档基础

编写Swagger文档的核心在于使用Swagger注解来描述API的各种细节。Swagger注解主要包括以下几种：

@Api：用于标记控制器类。
@ApiOperation：用于描述控制器中的一个操作（方法）。
@ApiParam：用于描述操作（方法）中的参数。
@ApiResponse：用于描述操作（方法）的响应。
@ApiModel：用于描述数据模型。

下面是一个使用Swagger编写API文档的例子：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(value = "User REST API", description = "Operations on users")
public class UserController {

    @GetMapping("/user")
    @ApiOperation(value = "Get user information by ID", notes = "This API retrieves user information by user ID", response = User.class)
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "Successful response"),
        @ApiResponse(code = 400, message = "Invalid user ID"),
        @ApiResponse(code = 404, message = "User not found")
    })
    public User getUserById(@ApiParam(value = "User ID", required = true) @RequestParam String id) {
        // TODO: Implement the logic to retrieve user information by ID
        return new User(id, "John Doe", "john.doe@example.com");
    }
}

理解和使用注解

在编写Swagger文档时，注解是描述API的重要工具。下面是一些常用的Swagger注解：

@Api：用于标记控制器类，指定控制器类的描述信息。
@ApiOperation：用于标记控制器中的方法，描述方法的作用和返回值类型。
@ApiParam：用于标记方法中的参数，描述参数的名称、类型、是否必须等信息。
@ApiResponse：用于描述方法的响应，包括HTTP状态码和响应体的信息。
@ApiModel：用于描述数据模型，定义数据模型的属性和类型。

示例代码解析

在上述示例代码中，我们定义了一个UserController控制器类，用于提供用户相关的API接口。代码中使用了多个Swagger注解来描述API的各个方面：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(value = "User REST API", description = "Operations on users")
public class UserController {

    @GetMapping("/user")
    @ApiOperation(value = "Get user information by ID", notes = "This API retrieves user information by user ID", response = User.class)
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "Successful response"),
        @ApiResponse(code = 400, message = "Invalid user ID"),
        @ApiResponse(code = 404, message = "User not found")
    })
    public User getUserById(@ApiParam(value = "User ID", required = true) @RequestParam String id) {
        // TODO: Implement the logic to retrieve user information by ID
        return new User(id, "John Doe", "john.doe@example.com");
    }
}

代码解析

@RestController：这是一个Spring MVC注解，表示这是一个控制器类。
@Api：标记控制器类，描述该控制器的作用。
@GetMapping("/user")：定义一个GET请求的API，URL路径为/user。
@ApiOperation(value = "Get user information by ID", notes = "This API retrieves user information by user ID", response = User.class)：描述该方法的作用和返回值类型。
@ApiResponses(value = { ... })：描述该方法可能返回的不同响应，包括HTTP状态码和响应信息。
@ApiParam(value = "User ID", required = true) @RequestParam String id：描述方法参数id的名称、类型和是否必须。

通过这种方式，Swagger注解帮助自动地生成了API的文档，使得开发人员和非技术人员都能够方便地理解和使用API。

测试Swagger API

使用Swagger UI测试API

在配置了Swagger UI之后，可以通过Swagger UI来测试API。以下是测试API的具体步骤：

启动应用：确保您的应用程序已经启动并运行。
访问Swagger UI：在浏览器中访问http://localhost:8080/swagger-ui.html，将会看到Swagger UI的界面。
选择API：在Swagger UI界面中选择要测试的API操作。
填写参数：根据Swagger文档中的描述，填写相应的参数值。
发送请求：点击“Try it out”按钮，发送请求并查看返回的结果。
查看结果：在Swagger UI界面中查看返回的响应信息，包括HTTP状态码和响应体。

掌握常用测试方法

在使用Swagger UI测试API时，可以掌握以下常用测试方法：

GET请求测试：通过填写URL和参数，发送GET请求，查看返回的数据。
POST请求测试：通过填写URL和请求体，发送POST请求，查看返回的数据。
PUT请求测试：通过填写URL和请求体，发送PUT请求，查看返回的数据。
DELETE请求测试：通过填写URL和参数，发送DELETE请求，查看返回的数据。
验证响应：通过查看返回的HTTP状态码和响应体，验证API的正确性。

通过Swagger验证API

在测试API时，可以通过以下几个方面验证API的正确性：

状态码验证：检查返回的HTTP状态码是否符合预期。例如，成功响应的状态码应为200。
响应体验证：验证返回的响应体是否符合预期的数据格式和内容。
参数验证：验证请求参数的正确性和有效性。
错误处理验证：验证在输入无效参数或执行失败操作时，API是否能够正确返回错误信息。
接口文档验证：验证Swagger文档中描述的API信息是否与实际实现一致。

示例项目

我们可以通过上述示例项目中的用户API来进行测试。例如，通过发送GET请求到/user来获取用户信息，并通过Swagger UI来进行测试和验证。

集成Swagger到项目

将Swagger集成到现有项目中

将Swagger集成到现有项目中通常需要以下步骤：

添加Swagger依赖：在项目的构建文件中添加Swagger相关的依赖。
配置Swagger资源文件：在项目的配置文件中配置Swagger的基本信息，例如API的标题、版本等。
配置Swagger UI：将Swagger UI的静态资源文件复制到项目中，并配置静态资源的路径。
配置Swagger配置类：创建一个Swagger配置类，配置Swagger的相关信息。
配置Swagger UI路由：在项目的路由配置文件中配置Swagger UI的路由。

与Spring Boot等框架的集成

将Swagger集成到Spring Boot项目中，可以通过以下步骤实现：

添加Swagger依赖：在项目的pom.xml文件中添加Swagger依赖。

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.5.21</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-jaxrs</artifactId>
    <version>1.5.21</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-ui</artifactId>
    <version>3.29.0</version>
</dependency>

配置Swagger配置类：创建一个Swagger配置类，配置Swagger的相关信息。

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponses;
import io.swagger.annotations.ApiResponse;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(value = "User REST API", description = "Operations on users")
public class UserController {

    @GetMapping("/user")
    @ApiOperation(value = "Get user information by ID", notes = "This API retrieves user information by user ID", response = User.class)
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "Successful response"),
        @ApiResponse(code = 400, message = "Invalid user ID"),
        @ApiResponse(code = 404, message = "User not found")
    })
    public User getUserById(@ApiParam(value = "User ID", required = true) @RequestParam String id) {
        // TODO: Implement the logic to retrieve user information by ID
        return new User(id, "John Doe", "john.doe@example.com");
    }
}

配置Swagger UI路由：在项目的WebMvcConfigurer中配置Swagger UI的路由。

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class SwaggerUiConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
            .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

使用Docker容器化Swagger

使用Docker容器化Swagger可以更方便地部署和运行Swagger服务。以下是使用Docker容器化Swagger的具体步骤：

编写Dockerfile：创建一个Dockerfile，定义Swagger服务的构建和运行环境。

FROM openjdk:8-jre-alpine
COPY target/my-api.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]

构建Docker镜像：使用Docker命令构建一个Docker镜像。

docker build -t my-api .

启动Docker容器：使用Docker命令启动一个Docker容器。

docker run -p 8080:8080 -d my-api

通过以上步骤，Swagger服务就可以在Docker容器中运行，便于部署和管理。

Swagger进阶技巧

参数校验与安全设置

在使用Swagger时，可以通过定义参数校验规则来确保API的输入参数符合预期。例如，可以定义参数的类型、长度、格式等。此外，Swagger还支持通过配置安全设置来保护API的安全性。

参数校验规则：定义参数的校验规则，确保API的输入参数符合预期。
安全设置：配置安全设置，保护API的安全性。

示例代码

以下是一个使用Swagger进行参数校验和安全设置的例子：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(value = "User REST API", description = "Operations on users")
public class UserController {

    @GetMapping("/user")
    @ApiOperation(value = "Get user information by ID", notes = "This API retrieves user information by user ID", response = User.class)
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "Successful response"),
        @ApiResponse(code = 400, message = "Invalid user ID"),
        @ApiResponse(code = 404, message = "User not found")
    })
    public User getUserById(@ApiParam(value = "User ID", required = true, example = "12345") @RequestParam String id) {
        // TODO: Implement the logic to retrieve user information by ID
        return new User(id, "John Doe", "john.doe@example.com");
    }
}

代码解析

@ApiParam(value = "User ID", required = true, example = "12345")：定义了参数id的名称、是否必须以及示例值。
@ApiResponses(value = { ... })：描述了该方法可能返回的不同响应，包括HTTP状态码和响应信息。

个性化Swagger界面

Swagger UI提供了丰富的配置选项，可以对Swagger界面进行个性化设置。例如，可以修改Swagger UI的主题、页头、页脚等。

修改主题：通过配置主题来改变Swagger UI的颜色和样式。
自定义页头页脚：通过配置自定义页头页脚来增加Swagger UI的信息和美观度。
增加自定义样式：通过增加自定义CSS和JavaScript来进一步个性化Swagger UI。

示例代码

以下是一个使用Swagger UI进行个性化设置的例子：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(value = "User REST API", description = "Operations on users")
public class UserController {

    @GetMapping("/user")
    @ApiOperation(value = "Get user information by ID", notes = "This API retrieves user information by user ID", response = User.class)
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "Successful response"),
        @ApiResponse(code = 400, message = "Invalid user ID"),
        @ApiResponse(code = 404, message = "User not found")
    })
    public User getUserById(@RequestParam String id) {
        // TODO: Implement the logic to retrieve user information by ID
        return new User(id, "John Doe", "john.doe@example.com");
    }
}

代码解析

@ApiOperation：定义了方法的描述信息。
@ApiResponses：定义了方法的响应信息。

常见问题及解决方案

在使用Swagger过程中，可能会遇到一些常见问题。以下是一些常见问题及其解决方案：

Swagger文档未生成：检查是否正确配置了Swagger的依赖和配置类。
Swagger UI界面未加载：检查是否正确配置了Swagger UI的静态资源和路由。
API操作未显示：检查是否正确使用了Swagger注解来描述API。
Swagger版本不匹配：确保使用的Swagger版本与项目兼容。
Swagger UI界面显示问题：尝试清除浏览器缓存或使用其他浏览器测试。

示例代码

以下是一个解决Swagger文档未生成的问题的例子：

检查依赖配置：确保在项目的pom.xml文件中正确配置了Swagger依赖。

<dependencies>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.5.21</version>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-jaxrs</artifactId>
        <version>1.5.21</version>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-ui</artifactId>
        <version>3.29.0</version>
    </dependency>
</dependencies>

检查配置类：确保Swagger配置类中的配置信息正确。


import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.jaxrs.config.BeanConfig;
import io.swagger.jaxrs.listing.ApiListingResource;
import io.swagger.jaxrs.listing.SwaggerSerializers;
import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import javax.ws.rs.ext.Provider;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Provider
    public class SwaggerConfigInitializer implements ServletConfig {
        @Override
        public void init(ServletConfig servletConfig) throws ServletException {
            BeanConfig beanConfig = new BeanConfig();
            beanConfig.setTitle("My API");
            beanConfig.setDescription("My API Documentation");
            beanConfig.setVersion("1.0.0");
            beanConfig.setSchemes(new String[]{"http", "https"});
            beanConfig.setBasePath("/api");
            beanConfig.setHost("localhost:8080");
            beanConfig.setPrettyPrint(true);
            beanConfig.setProduces(new String[]{"application/json"});
            beanConfig.setResourcePackage("com.example.api");
            beanConfig.setScan(true);
        }
    }

    @Provider
    public class SwaggerConfigResourceConfig {
        @ApiOperation(value = "Swagger Configuration Resource")
        public void configure() {
            SwaggerSerializers.register();
        }
    }
}
``

通过以上示例和代码展示，读者可以更好地理解和应用Swagger的相关知识。

点击查看更多内容

为 TA 点赞

若觉得本文不错，就分享一下吧！

评论

评论

共同学习，写下你的评论

评论加载中...

展开查看更多评论

作者其他优质文章

正在加载中

狐的传说

手记
篇

粉丝

88

获赞与收藏

555

关注作者，订阅最新文章

阅读免费教程

Hibernate 入门教程

29个小节 6370 94

HTTP 入门教程

28个小节 37988 651

后端通用面试教程

41个小节 30980 346

推荐

评论

收藏

共同学习，写下你的评论



感谢您的支持，我会继续努力的～

扫码打赏，你说多少就多少

赞赏金额会直接到老师账户

支付方式

打开微信扫一扫，即可进行扫码打赏哦

今天注册有机会得

100积分直接送

付费专栏免费学

大额优惠券免费领

立即参与放弃机会

点击
抽奖

慕课手记新用户专享福利

恭喜你，你的运气太好了，居然抽中了 100个积分！

恭喜你，抽中了价值元的专栏！

太棒了，直接落到你账户里！

积分商城里的罗技鼠标、机械键盘、
Kindle 阅读器、小米平衡车
Apple iPad （10.2英寸）、大额优惠券
在等着你去兑换了噢

作者：

免费赠送

兑换码：1111222211 复制

优惠券可用于购买实战课、体系课
无门槛使用

先去看看，有什么好东西马上兑换我爱学习，选课去


热搜

最近搜索清空

Swagger学习：新手入门指南

Swagger的定义和作用

Swagger的核心概念

Swagger的优势和应用场景

示例项目

选择合适的Swagger版本

开发环境搭建

示例项目

使用Swagger编写API文档基础

理解和使用注解

示例代码解析

代码解析

使用Swagger UI测试API

掌握常用测试方法

通过Swagger验证API

示例项目

将Swagger集成到现有项目中

与Spring Boot等框架的集成

使用Docker容器化Swagger

参数校验与安全设置

示例代码

代码解析

个性化Swagger界面

示例代码

代码解析

常见问题及解决方案

示例代码

阅读免费教程