自动化API文档生成与Swagger UI集成：API文档，如何从枯燥变得生动有趣？

🏆本文收录于「滚雪球学SpringBoot」专栏(专栏全网一个名)，手把手带你零基础入门Spring Boot，从入门到就业，助你早日登顶实现财富自由🚀；同时，欢迎大家关注&&收藏&&订阅！持续更新中，up！up！up！！

环境说明：Windows 10 + IntelliJ IDEA 2021.3.2 + Jdk 1.8

📚 前言

  API文档，可能对很多开发者来说，都是一个让人头疼的话题。每当新项目开始，手动编写和维护文档似乎是一项永远也做不完的任务——总是在代码更新时，文档也跟不上，搞得自己和团队成员都头大。是不是这么回事？🤔

  但，如果我告诉你有一种方法，能够自动化生成这些文档，且不需要担心和代码同步的问题，你是不是会觉得有点儿小兴奋？今天，我要给大家介绍一个神奇的工具——Swagger，它能自动读取你的代码注释，根据OpenAPI规范，自动生成API文档，并且通过Swagger UI提供交互式调试，极大提高开发和使用API的效率。是不是很吸引人？那就继续往下看吧！

📝 目录

• 1. 为什么选择Swagger？ 🤔
• 2. 基础概念：OpenAPI与Swagger 🛠️
• 3. 环境搭建：如何配置Swagger？ 🏗️
• 4. 自动化生成文档：通过注释代码 🧑‍💻
• 5. Swagger UI：让文档“活”起来 🎮
• 6. 从零开始：一个简单的API文档示例 🌱
• 7. 自定义Swagger UI：加入你的个性 🎨
• 8. 总结：Swagger的未来，你准备好了吗？ 🔮

1. 为什么选择Swagger？ 🤔

首先，先聊聊为什么这么多开发者都推荐使用Swagger。想象一下，每次你开发一个API时，不用再为写文档而烦恼，也不需要担心文档和代码不同步。Swagger能通过读取代码中的注释，自动生成文档，而且每当API有改动时，文档会自动更新。是不是特别省心？👍

不仅如此，Swagger还让文档变得更加交互式，你可以直接在文档页面上发送请求、查看响应，而不需要再去写大量的测试代码，或者手动进行接口调试。用过一次，可能就会发现它能极大地提高你的开发效率，简直就是开发者的“救命稻草”！🌟

2. 基础概念：OpenAPI与Swagger 🛠️

在深入实现之前，我们先来澄清两个概念：OpenAPI 和 Swagger。相信很多人对这两个名字都有些许混淆，它们之间到底是什么关系呢？

OpenAPI规范

OpenAPI（前身叫Swagger规范）是一个描述RESTful API的标准规范，它定义了API的结构，包括路由、请求类型、请求和响应的数据格式等等。简单说，OpenAPI就是一份标准的“API合同”，让所有开发者都能按照相同的格式来描述API，避免了信息不对称的问题。

Swagger

Swagger是一套基于OpenAPI规范的开源工具，提供了多种功能，最常用的就是自动生成API文档、进行API调试等。换句话说，Swagger是OpenAPI规范的具体实现，它让你能够轻松地通过注释代码来生成和展示API文档。

3. 环境搭建：如何配置Swagger？ 🏗️

开始之前，咱们得先把环境搭好。首先，确保你有一个Node.js项目。如果你还没创建，可以先用这个命令快速初始化一个项目：

npm init -y

然后，安装Swagger相关的依赖库：

npm install swagger-jsdoc swagger-ui-express

有了这些依赖后，就可以在你的项目里配置Swagger啦。打开一个新的 app.js 文件，写入以下代码：

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerJsdoc = require('swagger-jsdoc');

const app = express();

// Swagger配置
const options = {
  swaggerDefinition: {
    info: {
      title: '我的API文档',
      version: '1.0.0',
      description: '这是一个Swagger API文档示例',
    },
    basePath: '/',
  },
  apis: ['./routes/*.js'], // 自动读取该目录下的路由文件
};

const swaggerSpec = swaggerJsdoc(options);

// 使用Swagger UI
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

app.listen(3000, () => {
  console.log('服务已经启动，API文档可以通过 http://localhost:3000/api-docs 查看');
});

这样就搭好了一个简单的Swagger环境。接下来，你只需要通过注释代码来生成文档，Swagger会自动解析这些注释，展示给你。

4. 自动化生成文档：通过注释代码 🧑‍💻

接下来的操作可有趣了！你只需要在代码中加上特定格式的注释，Swagger就会根据这些注释自动生成文档。

看看这个例子，我们要定义一个简单的获取用户列表的API：

/**
 * @swagger
 * /api/v1/users:
 *   get:
 *     description: 获取所有用户
 *     responses:
 *       200:
 *         description: 用户列表
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 type: object
 *                 properties:
 *                   id:
 *                     type: integer
 *                   name:
 *                     type: string
 */
app.get('/api/v1/users', (req, res) => {
  res.status(200).json([{ id: 1, name: '张三' }]);
});

在这里，我们用 @swagger 注释标注了API的路径、请求方法、描述和返回格式。Swagger会根据这些注释自动生成接口文档，简直是懒人必备的神器！🎯

5. Swagger UI：让文档“活”起来 🎮

Swagger UI不仅能生成静态文档，更能提供交互式调试功能！这意味着开发者可以直接在浏览器中进行API请求，查看返回结果。想象一下，想试试一个接口，只需点击几下，Swagger UI就会帮你发送请求，显示响应数据，是不是比手动测试API方便多了？

比如，你可以直接在文档页面上点击 "Try it out"，填入必要的参数，然后直接看到API的返回结果。这个过程比写一堆测试代码、用Postman手动调试要轻松得多！

6. 从零开始：一个简单的API文档示例 🌱

接下来，我们来实际操作一下。假设我们要做一个用户管理系统的API，包含获取用户和创建用户两个接口。整个过程包括：

1. 配置Swagger
2. 编写路由并加注释
3. 通过Swagger UI查看和调试API文档

等你完成这些步骤后，你就能在Swagger UI里看到漂亮的API文档，并且直接在文档页面上测试API接口。

7. 自定义Swagger UI：加入你的个性 🎨

Swagger UI的默认样式看起来已经很简洁、漂亮了，但如果你想让它更符合你团队的风格，或者加点个性化元素，完全可以自定义。你可以修改它的主题、颜色、字体，甚至加入你公司或项目的Logo，完全没有问题。

通过简单的CSS调整，你可以让Swagger UI看起来既专业又酷炫，给开发者和用户带来更好的体验。✨

8. 总结：Swagger的未来，你准备好了吗？ 🔮

通过今天的介绍，相信你已经对Swagger有了更深入的了解。它不仅能自动生成API文档，还能让文档变得交互式，让你轻松进行接口调试。更重要的是，Swagger可以帮助你保持文档和代码同步，减少了文档过期和不一致的问题。

未来，随着API数量的增加，Swagger将成为开发者的必备工具。它不仅节省了时间，还提高了团队的工作效率。对了，你是不是已经迫不及待想要开始用Swagger来提升自己的开发效率了呢？😁

👀 结语：

那你准备好让API文档从“枯燥”变“生动”了吗？你有没有试过Swagger？如果没有，赶快动手试试吧！

☀️建议/推荐你

  无论你是计算机专业的学生，还是对编程有兴趣的小伙伴，都建议直接毫无顾忌的学习此专栏「滚雪球学SpringBoot」(专栏全网独家统一名)，bug菌郑重承诺，凡是学习此专栏的同学，均能获取到所需的知识和技能，全网最快速入门Java编程，就像滚雪球一样，越滚越大，指数级提升。

  码字不易，如果这篇文章对你有所帮助，帮忙给bug菌来个一键三连(关注、点赞、收藏) ，您的支持就是我坚持写作分享知识点传播技术的最大动力。   同时也推荐大家关注我的硬核公众号:「猿圈奇妙屋」 ；以第一手学习bug菌的首发干货，不仅能学习更多技术硬货，还可白嫖最新BAT大厂面试真题、4000G Pdf技术书籍、万份简历/PPT模板、技术文章Markdown文档等海量资料，你想要的我都有！

📣关于我

  我是bug菌(全网一个名)，CSDN | 掘金 | 腾讯云 | 华为云 | 阿里云 | 51CTO | InfoQ 等社区博客专家，历届博客之星Top30，掘金年度人气作者Top40，51CTO年度博主Top12，掘金等平台签约作者，华为云 | 阿里云| 腾讯云等社区优质创作者，全网粉丝合计30w+ ；硬核微信公众号「猿圈奇妙屋」，欢迎你的加入！免费白嫖最新BAT互联网公司面试题、4000G pdf电子书籍、简历模板等海量资料。

-End-