首页手记 Swagger学习：新手入门教程

Swagger学习：新手入门教程

标签：

设计接口测试 API

概述

本文提供了关于Swagger学习的全面指南，涵盖了Swagger的基本概念、作用和优势，以及如何安装和配置Swagger。文章还详细介绍了使用Swagger编写API文档的方法和测试调试技巧。读者可以深入了解Swagger的高级功能和实际应用案例。

Swagger学习：新手入门教程

Swagger简介

什么是Swagger

Swagger 是一套用于构建 RESTful 风格 API 的工具和规范。它通过定义一组标准的注解来描述 API 的结构和行为，自动生成 API 文档，并提供在线测试功能。Swagger 的核心目标是简化 API 的开发、维护和测试过程，提高前后端开发人员之间的沟通效率。

Swagger 由 SmartBear 旗下的公司 Apigee 开发和维护。目前，Swagger 已成为世界上最流行的 API 文档工具之一，并得到了广泛的应用。最新版本称为 OpenAPI，是一个独立的规范，不再依赖于 Swagger。

Swagger的作用和优势

Swagger 提供了多种工具和服务，帮助开发人员更高效地管理 API。以下是 Swagger 的一些主要作用和优势：

自动生成文档：Swagger 允许开发人员通过简单的注解定义 API，然后自动生成详细的文档。这不仅节省了编写文档的工作量，还保证了文档与代码的一致性。
在线测试：Swagger 提供了一个在线测试平台（Swagger UI），开发人员可以直接在浏览器中测试 API 的功能。这有助于快速迭代和调试 API。
协作与共享：Swagger 可以轻松地将 API 文档分享给其他开发人员或客户。Swagger UI 支持多种输出格式（如 JSON、YAML），方便在不同平台上使用。
版本管理：Swagger 支持多版本管理，便于开发人员为 API 的不同版本创建独立的文档。

Swagger与OpenAPI的关系

Swagger 和 OpenAPI 之间存在一定的关系，但也有明显的区别。OpenAPI 是一个独立的规范，而 Swagger 是一套基于 OpenAPI 规范的工具集。具体来说：

OpenAPI 规范：OpenAPI 规范定义了一系列标准来描述 RESTful API 的结构和行为。它是开放的，不受任何特定实现或工具的约束。
Swagger 工具集：Swagger 是一套基于 OpenAPI 规范的工具集，包括 Swagger Editor、Swagger UI、Swagger Codegen 等。Swagger 提供了更丰富的功能来支持 API 的开发、维护和测试。

安装和配置Swagger

安装Swagger所需工具

在开始使用 Swagger 之前，需要安装一些必要的工具。推荐使用以下工具进行开发：

Swagger Editor：一个集成开发环境（IDE），允许开发人员编写和测试 OpenAPI 文档。可以在 https://editor.swagger.io/ 在线访问。
Swagger UI：一个用于展示 OpenAPI 文档的 Web 应用程序。它支持通过浏览器测试 API，查看示例响应等。
Swagger Codegen：一个代码生成器，可以根据 OpenAPI 文档自动生成后端代码（如 Java、Python）和客户端库（如 JavaScript、Node.js）。

配置Swagger在项目中的使用

配置 Swagger 在项目中使用需要进行以下步骤：

添加 Swagger 依赖：在项目中添加 Swagger 相关的依赖。例如，如果你使用的是 Java Spring Boot，可以在 pom.xml 或 build.gradle 文件中添加如下依赖：

Maven 依赖（Spring Boot）：

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

Gradle 依赖（Spring Boot）：

implementation 'io.springfox:springfox-swagger2:2.9.2'
implementation 'io.springfox:springfox-swagger-ui:2.9.2'

配置 Swagger：在 Spring Boot 项目中，可以通过配置 SwaggerConfig 类来启用 Swagger。以下是一个简单的 SwaggerConfig 配置示例：

package com.example.demo.config;

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();
   }
}

访问 Swagger UI：配置完成后，可以在浏览器中访问 http://localhost:8080/swagger-ui.html 来查看 Swagger UI 并测试 API。

使用Swagger编写API文档

API的基本结构

一个完整的 API 文档通常包含以下几个部分：

基本信息：包括 API 的版本、描述等基本信息。
路径定义：定义 API 的路径（URL），每个路径上可以有多个操作（如 GET、POST）。
请求和响应：定义每个操作的请求参数、请求体、响应码和响应体。

以下是一个简单的 OpenAPI 文档示例：

openapi: 3.0.0
info:
  description: "这是一个简单的 API 文档示例"
  version: "1.0.0"
  title: "API 示例"
paths:
  /users:
    get:
      summary: "获取用户列表"
      description: "返回所有用户的信息"
      responses:
        "200":
          description: "用户列表"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
  /users/{id}:
    get:
      summary: "获取单个用户"
      parameters:
        - name: id
          in: path
          required: true
          description: "用户 ID"
          schema:
            type: integer
      responses:
        "200":
          description: "用户信息"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

使用Swagger注解定义API

在实际项目中，通常使用 Swagger 注解来定义 API 的结构和行为。以下是一个使用 Java Spring Boot 的示例：

package com.example.demo.controller;

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

import java.util.Arrays;
import java.util.List;

@RestController
@Api(value = "用户管理", tags = "用户管理相关API")
public class UserController {

    @RequestMapping("/users")
    @ApiOperation(value = "获取用户列表", notes = "返回所有用户的信息")
    public List<User> getUsers() {
        return Arrays.asList(new User(1, "张三", "zhangsan@example.com"),
                             new User(2, "李四", "lisi@example.com"));
    }

    @RequestMapping("/users/{id}")
    @ApiOperation(value = "获取单个用户", notes = "根据用户 ID 返回用户信息")
    public User getUserById(@PathVariable int id) {
        // 假设这里返回根据 ID 查找的用户对象
        return new User(id, "张三", "zhangsan@example.com");
    }

    @ApiModel(value = "用户对象", description = "用户相关数据结构")
    public static class User {
        private int id;
        private String name;
        private String email;

        public User(int id, String name, String email) {
            this.id = id;
            this.name = name;
            this.email = email;
        }

        // getter 和 setter 方法
        public int getId() { return id; }
        public String getName() { return name; }
        public String getEmail() { return email; }
    }
}

添加请求参数和响应示例

在定义 API 时，可以使用 Swagger 注解来指定请求参数、响应示例等信息。以下是一个示例：

package com.example.demo.controller;

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.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(value = "用户管理", tags = "用户管理相关API")
public class UserController {

    @GetMapping("/users")
    @ApiOperation(value = "获取用户列表", notes = "返回所有用户的信息")
    public List<User> getUsers(@ApiParam(value = "页码", required = true) @RequestParam int page) {
        // 假设这里根据页码返回用户列表
        return Arrays.asList(new User(1, "张三", "zhangsan@example.com"),
                             new User(2, "李四", "lisi@example.com"));
    }

    @GetMapping("/users/{id}")
    @ApiOperation(value = "获取单个用户", notes = "根据用户 ID 返回用户信息")
    public User getUserById(@ApiParam(value = "用户 ID", required = true) @PathVariable int id) {
        // 假设这里返回根据 ID 查找的用户对象
        return new User(id, "张三", "zhangsan@example.com");
    }

    @ApiModel(value = "用户对象", description = "用户相关数据结构")
    public static class User {
        private int id;
        private String name;
        private String email;

        public User(int id, String name, String email) {
            this.id = id;
            this.name = name;
            this.email = email;
        }

        // getter 和 setter 方法
        public int getId() { return id; }
        public String getName() { return name; }
        public String getEmail() { return email; }
    }
}

测试和调试Swagger文档

使用Swagger UI测试API

Swagger UI 提供了一个在线测试平台，帮助开发人员快速测试 API 的功能。以下是一个示例：

启动 Swagger UI：配置好 Swagger 后，在浏览器中访问 http://localhost:8080/swagger-ui.html。
测试 API：在 Swagger UI 中选择要测试的 API 操作（如 GET /users），点击 "Try it out" 按钮，输入必要的参数，然后点击 "Execute" 按钮来测试 API。

查找和修正常见错误

在测试 API 时，可能会遇到一些常见错误。以下是一些常见的错误及修正常见方法：

404 错误：这通常表示请求的资源不存在。请检查路径是否正确，以及 API 是否已正确部署。
500 错误：这表示服务器端发生了错误。请检查服务器日志，找到具体的错误信息并进行修复。
参数错误：如果请求参数不符合定义，Swagger UI 会显示相应的错误信息。请检查参数定义是否正确，并确保请求参数与定义一致。

Swagger的高级功能

使用Tag分类API

Swagger 允许开发人员使用 tags 来对 API 进行分类。这有助于理清 API 的结构，并使文档更具可读性。例如：

openapi: 3.0.0
info:
  description: "这是一个简单的 API 文档示例"
  version: "1.0.0"
  title: "API 示例"
paths:
  /users:
    get:
      summary: "获取用户列表"
      description: "返回所有用户的信息"
      tags:
        - name: "用户管理"
      responses:
        "200":
          description: "用户列表"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
  /users/{id}:
    get:
      summary: "获取单个用户"
      parameters:
        - name: id
          in: path
          required: true
          description: "用户 ID"
          schema:
            type: integer
      tags:
        - name: "用户管理"
      responses:
        "200":
          description: "用户信息"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

定义全局配置和安全设置

Swagger 允许定义全局配置和安全设置，以便于统一管理 API 的配置。例如：

openapi: 3.0.0
info:
  description: "这是一个简单的 API 文档示例"
  version: "1.0.0"
  title: "API 示例"
servers:
  - url: "http://localhost:8080"
    description: "本地开发环境"
paths:
  /users:
    get:
      summary: "获取用户列表"
      description: "返回所有用户的信息"
      responses:
        "200":
          description: "用户列表"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

集成第三方库和工具

Swagger 可以集成多种第三方库和工具来扩展其功能。例如，Swagger Codegen 可以生成后端代码和客户端库，并集成到开发流程中。以下是一个使用 Swagger Codegen 生成 Java 客户端库的示例：

安装 Swagger Codegen：

mvn io.swagger:swagger-codegen-cli:generate -Durl=http://localhost:8080/v2/api-docs -Dtype=java

生成 Java 客户端库：

java -jar swagger-codegen-cli.jar generate -i http://localhost:8080/v2/api-docs -l java -o ../api-client

生成的客户端库可以集成到 Java 项目中，用于发起 API 请求：

package com.example.demo.client;

import com.example.demo.api.UserApi;
import com.example.demo.model.User;

public class UserClient {

    public static void main(String[] args) {
        UserApi userApi = new UserApi();

        try {
            // 获取用户列表
            List<User> users = userApi.getUsers();
            System.out.println(users);

            // 获取单个用户
            User user = userApi.getUserById(1);
            System.out.println(user);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

实践案例分享

Swagger在实际项目中的应用

Swagger 在实际项目中的应用非常广泛，可以显著提高 API 的开发效率和质量。以下是一些具体的应用案例：

电商平台：电商平台的订单系统使用 Swagger 来定义和维护订单相关的 API。开发人员可以通过 Swagger 自动生成文档，并通过 Swagger UI 在线测试订单操作的正确性。

package com.example.platform.order;

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

@RestController
@Api(value="订单管理", tags="订单管理相关API")
public class OrderController {

   @RequestMapping("/orders")
   @ApiOperation(value="获取订单列表", notes="返回所有订单的信息")
   public List<Order> getOrders() {
       // 返回订单列表的逻辑
       return Arrays.asList(new Order(1, "订单1", 100.0),
                            new Order(2, "订单2", 200.0));
   }
}

@ApiModel(value="订单对象", description="订单相关数据结构")
public static class Order {
   private int id;
   private String description;
   private double amount;

   public Order(int id, String description, double amount) {
       this.id = id;
       this.description = description;
       this.amount = amount;
   }

   // getter 和 setter 方法
   public int getId() { return id; }
   public String getDescription() { return description; }
   public double getAmount() { return amount; }
}

社交媒体应用：社交媒体应用使用 Swagger 来定义用户注册、登录、发布内容等 API。这不仅提高了前后端开发人员之间的沟通效率，还使得文档与代码保持一致。

package com.example.socialmedia;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(value="用户管理", tags="用户管理相关API")
public class UserController {

   @GetMapping("/users")
   @ApiOperation(value="获取用户列表", notes="返回所有用户的信息")
   public List<User> getUsers() {
       // 返回用户列表的逻辑
       return Arrays.asList(new User(1, "张三", "zhangsan@example.com"),
                            new User(2, "李四", "lisi@example.com"));
   }

   @PostMapping("/users/register")
   @ApiOperation(value="注册用户", notes="注册新用户")
   public void registerUser(User user) {
       // 用户注册逻辑
   }

   @ApiModel(value="用户对象", description="用户相关数据结构")
   public static class User {
       private int id;
       private String name;
       private String email;

       public User(int id, String name, String email) {
           this.id = id;
           this.name = name;
           this.email = email;
       }

       // getter 和 setter 方法
       public int getId() { return id; }
       public String getName() { return name; }
       public String getEmail() { return email; }
   }
}

金融服务：金融服务应用使用 Swagger 来定义账户管理、交易记录查询等 API。Swagger 的版本管理功能使得不同版本的 API 文档能够轻松管理。

package com.example.finance;

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

@RestController
@Api(value="账户管理", tags="账户管理相关API")
public class AccountController {

   @GetMapping("/accounts")
   @ApiOperation(value="获取账户列表", notes="返回所有账户的信息")
   public List<Account> getAccounts() {
       // 返回账户列表的逻辑
       return Arrays.asList(new Account(1, "账户1", 1000.0),
                            new Account(2, "账户2", 2000.0));
   }
}

@ApiModel(value="账户对象", description="账户相关数据结构")
public static class Account {
   private int id;
   private String description;
   private double balance;

   public Account(int id, String description, double balance) {
       this.id = id;
       this.description = description;
       this.balance = balance;
   }

   // getter 和 setter 方法
   public int getId() { return id; }
   public String getDescription() { return description; }
   public double getBalance() { return balance; }
}

分享其他开发者的经验

许多开发团队分享了他们在使用 Swagger 时的经验和最佳实践。例如：

持续集成/持续部署（CI/CD）：一些团队将 Swagger 文档的生成和验证集成到了 CI/CD 流程中，确保每次代码提交时 API 文档的一致性。
```
mvn clean install io.swagger:swagger-core:1.5.20:generate-swagger-json
```

自动化测试：通过 Swagger 生成的客户端库，团队可以编写自动化测试脚本来验证 API 的功能和性能。

package com.example.demo.test;

import com.example.demo.api.UserApi;
import io.restassured.RestAssured;
import io.restassured.response.Response;
import org.testng.Assert;
import org.testng.annotations.BeforeClass;
import org.testng.annotations.Test;

public class UserApiTest {

   @BeforeClass
   public void setup() {
       RestAssured.baseURI = "http://localhost:8080";
       RestAssured.port = 8080;
   }

   @Test
   public void testGetUsers() {
       Response response = RestAssured.get("/users");
       Assert.assertEquals(response.getStatusCode(), 200);
       Assert.assertTrue(response.getBody().asString().contains("张三"));
   }
}

多语言支持：通过 Swagger Codegen 生成客户端库，可以支持多种编程语言（如 Java、Python、JavaScript），这使得跨平台开发更加灵活。
```
java -jar swagger-codegen-cli.jar generate -i http://localhost:8080/v2/api-docs -l python -o ../api-client-python
```

通过这些案例和经验分享，可以看到 Swagger 在现代 API 开发中的重要性。它不仅简化了开发流程，还提高了文档的质量和可维护性。

点击查看更多内容

为 TA 点赞

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

评论

评论

共同学习，写下你的评论

评论加载中...

展开查看更多评论

作者其他优质文章

正在加载中

胡说叔叔

手记
篇

粉丝

130

获赞与收藏

581

关注作者，订阅最新文章

阅读免费教程

设计模式入门教程

10个小节 21906 415

Dreamweaver 教程

25个小节 5062 102

Hibernate 入门教程

29个小节 6360 93

HTTP 入门教程

28个小节 37784 648

推荐

评论

收藏

共同学习，写下你的评论



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

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

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

支付方式

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

今天注册有机会得

100积分直接送

付费专栏免费学

大额优惠券免费领

立即参与放弃机会

点击
抽奖

慕课手记新用户专享福利

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

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

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

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

作者：

免费赠送

兑换码：1111222211 复制

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

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

热搜

最近搜索清空