学生程序设计能力提升平台源码分析（十一）接口文档生成以及规范化Apidoc

前言

2021SC@SDUSC

概述

在上一篇博客中，我们讲解了项目中git的使用，我们在开发时不仅要注意代码的规范性，更要注意版本控制和协作开发的相关事项，做好这点能够大大提高开发效率。

除此之外，优化开发流程还有很多方法，在这里我们就谈一谈与一个WEB项目开发紧密相关的对象——接口文档。

说到接口文档，可能很多前端和后端的程序员都会比较头疼，毕竟开发是前后端分离的，前后端的对接除了开发者亲自交流外，基本靠接口文档，但是往往接口文档会出现很多问题，比如格式，版本，语义等等。如何写好一个接口文档，是项目开发不可忽视的问题。

但是人工撰写，修改，管理接口文档十分麻烦，容易出错的同时效率也不高。

那么有什么能够提高效率的方法吗？答案是有的，比如使用自动化的接口文档工具，如swagger,apidoc等等。

在本项目中，接口文档通过APIdoc进行生成，修改和管理。

ApiDoc

简介

apidoc 是一个简单的 RESTful API 文档生成工具，它从代码注释中提取特定格式的内容生成文档。支持诸如 Go、Java、C++、Rust 等大部分开发语言，具体可使用 apidoc lang 命令行查看所有的支持列表。

apidoc 拥有以下特点：

1. 跨平台，linux、windows、macOS 等都支持；
2. 支持语言广泛，即使是不支持，也很方便扩展；
3. 支持多个不同语言的多个项目生成一份文档；
4. 输出模板可自