Go 语言项目开发实战
孔令飞
腾讯云资深工程师,前Red Hat、联想云工程师
新⼈⾸单¥69.9
2894 人已学习
课程目录
已更新 20 讲 / 共 54 讲
0/4登录后,你可以任选4讲全文学习。
开篇词 (1讲)
开篇词 | 从 0 开始搭建一个企业级 Go 应用
免费
课前必学 (3讲)
01 | IAM系统概述:我们要实现什么样的 Go 项目?
02 | 环境准备:如何安装和配置一个基本的 Go 开发环境?
03 | 项目部署:如何快速部署 IAM 系统?
实战第 1 站:规范设计 (8讲)
04 | 规范设计(上):项目开发杂乱无章,如何规范?
05 | 规范设计(下):commit 信息风格迥异、难以阅读,如何规范?
06 | 目录结构设计:如何组织一个可维护、可扩展的代码目录?
07 | 工作流设计:如何设计合理的多人开发模式?
08 | 研发流程设计(上):如何设计 Go 项目的开发流程?
09 | 研发流程设计(下):如何管理应用的生命周期?
10 | 设计方法:怎么写出优雅的 Go 项目?
11 | 设计模式:Go常用设计模式概述
实战第2站:基础功能设计或开发 (6讲)
12 | API 风格(上):如何设计RESTful API?
13 | API 风格(下):RPC API介绍
14 | 项目管理:如何编写高质量的Makefile?
15 | 研发流程实战:IAM项目是如何进行研发流程管理的?
16 | 代码检查:如何进行静态代码检查?
17 | API 文档:如何生成 Swagger API 文档 ?
特别放送 (2讲)
特别放送 | 给你一份清晰、可直接套用的Go编码规范
特别放送 | 给你一份Go项目中最常用的Makefile核心语法
Go 语言项目开发实战
15
15
1.0x
00:00/00:00
登录|注册

17 | API 文档:如何生成 Swagger API 文档 ?

你好,我是孔令飞。
作为一名开发者,我们通常讨厌编写文档,因为这是一件重复和缺乏乐趣的事情。但是在开发过程中,又有一些文档是我们必须要编写的,比如 API 文档。
一个企业级的 Go 后端项目,通常也会有个配套的前端。为了加快研发进度,通常是后端和前端并行开发,这就需要后端开发者在开发后端代码之前,先设计好 API 接口,提供给前端。所以在设计阶段,我们就需要生成 API 接口文档。
一个好的 API 文档,可以减少用户上手的复杂度,也意味着更容易留住用户。好的 API 文档也可以减少沟通成本,帮助开发者更好地理解 API 的调用方式,从而节省时间,提高开发效率。这时候,我们一定希望有一个工具能够帮我们自动生成 API 文档,解放我们的双手。Swagger 就是这么一个工具,可以帮助我们生成易于共享且具有足够描述性的 API 文档
接下来,我们就来看下,如何使用 Swagger 生成 API 文档。

Swagger 介绍

Swagger 是一套围绕 OpenAPI 规范构建的开源工具,可以设计、构建、编写和使用 REST API。Swagger 包含很多工具,其中主要的 Swagger 工具包括:
Swagger 编辑器:基于浏览器的编辑器,可以在其中编写 OpenAPI 规范,并实时预览 API 文档。https://editor.swagger.io 就是一个 Swagger 编辑器,你可以尝试在其中编辑和预览 API 文档。
Swagger UI:将 OpenAPI 规范呈现为交互式 API 文档,并可以在浏览器中尝试 API 调用。
Swagger Codegen:根据 OpenAPI 规范,生成服务器存根和客户端代码库,目前已涵盖了 40 多种语言。
确认放弃笔记?
放弃后所记笔记将不保留。
新功能上线,你的历史笔记已初始化为私密笔记,是否一键批量公开?
批量公开的笔记不会为你同步至部落
公开
同步至部落
取消
完成
0/1000字
划线
笔记
复制
该试读文章来自付费专栏《Go 语言项目开发实战》,如需阅读全部文章,
请订阅文章所属专栏新⼈⾸单¥69.9
立即订阅
登录 后留言

精选留言

由作者筛选后的优质留言将会公开显示,欢迎踊跃留言。
收起评论
返回
顶部