面向API技术文档作者的Git工作流 - Bump.sh

技术编写人员经常面临如何使API文档与不断变化的API设计保持同步的挑战。本文将探讨这一问题的解决方案，重点介绍如何通过并行开发和自动化工具来简化流程，帮助技术作者更高效地管理API文档。

---

## 为API文档使用Git工作流的好处

将Git纳入技术写作工作流程可以带来以下几方面的优势：

- **版本控制**：Git工作流能够对所有文档更改进行跟踪和版本管理，方便回滚和历史记录分析。
- **协作提升**：Git促进了技术作者与开发团队之间的协作，支持持续的反馈和改进。
- **自动化集成**：通过与CI/CD（持续集成/持续交付）管道的结合，能够在API代码库发生更改时自动更新文档。

尽管如此，并没有一种通用的解决方案适用于所有场景。接下来，我们将探讨技术编写人员可能遇到的常见情况，以及如何优化文档流程的工作流选项。

---

## 使用代码生成文档的挑战

通过代码注释直接生成OpenAPI规范文档是一种常见方法。例如，基于Java的Spring Boot库SpringDoc可以帮助从Java代码生成OpenAPI文档。然而，这种方法也存在以下问题：

1. **文档过于技术化**：生成的文档可能缺乏针对外部消费者的上下文。
2. **文档不完整**：由于时间限制，生成的文档可能存在遗漏。
3. **编辑复杂性**：技术作者需要直接修改源代码中的注释，这对专注于提高文档质量的技术作者来说是一项挑战。

为了解决这些问题，可以考虑以下改进建议：

### 将改进的文档合并到源代码中

技术作者可以向工程师提供改进后的文档，由工程师将其合并到源代码中。这种方法虽然效率较低，但可以在不改变现有开发流程的情况下提升文档质量。如果技术作者熟悉Git和代码，也可以直接创建特性分支，并利用CI/CD管道验证更改的正确性。

### 使用代码注释一次性生成文档

与其依赖代码注释生成文档，不如生成一次OpenAPI规范文档，并将其作为主要的真相来源。这种方式避免了技术作者频繁编辑源代码的需求，同时减少了从零开始编写基于YAML的OpenAPI文档的工作量。生成的OpenAPI文档可以存储在与代码相同或单独的存储库中。

---

## 对于绿地API设计，协作是关键

在设计新的（绿地）API时，采用设计优先的方法尤为重要。这意味着在实现API代码之前，先创建OpenAPI文档，使其成为API实现的真相来源。

然而，技术作者往往被排除在设计过程之外。实际上，让技术作者参与API设计过程可以带来以下好处：

- **设计输入**：技术作者能够从文档的角度提供设计建议，提升清晰性、一致性和可用性。
- **以用户为中心的文档**：早期参与有助于确保文档从一开始就满足目标受众的需求。
- **文档与API策略一致**：确保文档不仅具有信息性，还能与API计划的整体目标保持一致。

---

## Git工作流冲突：独立存储库的案例

在某些组织中，工程团队的工作流可能与技术作者的工作流产生冲突。例如：

- 技术作者无法及时更新存储在同一Git存储库中的文档，需等待开发周期完成。
- 技术作者的文档更改可能增加开发人员的工作量，导致效率降低。

为了解决这些问题，可以考虑将API文档存储在单独的Git存储库中。这种方法的优势包括：

- **文档管理灵活性**：文档可以独立于代码进行更新，方便修订和发布。
- **文档版本控制**：专门针对文档的更改历史记录，便于追踪和回滚。
- **跨团队协作**：非开发人员（如产品经理）也能更轻松地参与文档工作。

当然，这种方法需要额外创建独立的CI/CD管道来支持API文档的自动构建和发布。此外，需特别注意防止文档与代码不同步的问题。

---

## 结论

协调API文档与软件工程是一项持续的挑战。通过采用独立存储库、利用OpenAPI规范和自动化工具，技术作者可以与工程师更高效地协作，提供卓越的API文档体验。这不仅提升了文档质量，还改善了开发者的整体体验，从而推动API项目的成功。

---

原文链接: https://bump.sh/blog/git-workflows-for-api-technical-writers