5步解锁ShowDoc API：从集成到文档自动化全攻略

ShowDoc API是实现文档自动化的核心工具，它提供了一套完整的接口系统，让开发者能够通过编程方式管理文档内容。无论是自动化生成API文档、集成到CI/CD流程，还是构建自定义文档管理工具，ShowDoc API都能提供强大支持，帮助团队提升文档管理效率和自动化水平。

一、核心价值：为什么选择ShowDoc API

在现代软件开发中，文档管理往往是一个被忽视但至关重要的环节。ShowDoc API的核心价值在于它打破了传统手动维护文档的低效模式，为开发者提供了一种程序化管理文档的途径。通过ShowDoc API，你可以实现文档的自动创建、更新和维护，确保文档与代码同步更新，减少人工操作带来的错误和遗漏。

ShowDoc API的价值主要体现在以下几个方面：

1. 自动化文档生成：通过API接口，可以从代码注释、数据库结构等源头自动生成文档，减少手动编写的工作量。

2. 无缝集成到开发流程：可以将文档更新集成到CI/CD流程中，实现代码提交后自动更新文档。

3. 定制化文档管理：根据团队需求，通过API构建自定义的文档管理工具，满足特定的业务场景。

4. 批量操作能力：支持批量创建、更新文档和目录，提高大规模文档管理效率。

二、技术解析：ShowDoc API的工作原理

2.1 API架构概述

ShowDoc API采用RESTful风格设计，所有接口都位于server/Application/Api/Controller/OpenController.class.php文件中。这个控制器类包含了从页面操作到目录管理的所有API接口实现。

API请求的基本URL格式为：

http://your-showdoc-domain/server/index.php?s=/api/open/[接口名称]

2.2 认证机制详解 🔑

ShowDoc API采用双因素认证机制，确保接口调用的安全性。认证相关的逻辑在server/Application/Api/Model/ItemTokenModel.class.php中实现。

• API Key：用于识别项目身份，相当于项目的"身份证"。
• API Token：用于验证请求合法性，相当于项目的"密钥"。

认证流程如下：

1. 客户端在请求中提供api_key和api_token
2. 服务器端在ItemTokenModel中验证这两个参数的有效性
3. 验证通过后，才会执行后续的API操作

2.3 核心接口分类 📋

ShowDoc API主要分为以下几类：

1. 页面管理接口：包括创建、更新、删除页面等操作
2. 目录管理接口：包括创建目录、获取目录树等操作
3. 附件管理接口：包括上传、删除附件等操作

每个接口都有特定的参数要求和返回格式，具体可以参考ShowDoc的官方文档。

三、实践指南：ShowDoc API快速上手

3.1 准备工作

在开始使用ShowDoc API之前，需要完成以下准备工作：

1. 获取API凭证：在ShowDoc项目设置中生成api_key和api_token。
2. 熟悉API文档：了解各个接口的参数要求和返回格式。
3. 选择合适的HTTP客户端：可以使用curl、Postman或编程语言中的HTTP库。

3.2 基础接口调用示例

以下是几个常用接口的调用示例：

3.2.1 更新页面内容

# 创建或更新页面
curl -X POST "http://your-showdoc-domain/server/index.php?s=/api/open/updatePage" \
  -d "api_key=your_api_key" \
  -d "api_token=your_api_token" \
  -d "page_title=用户管理API" \
  -d "page_content=# 用户管理API\n\n## 获取用户列表\n\n- 请求方法: GET\n- URL: /api/users" \
  -d "cat_name=API文档"

3.2.2 创建目录

# 创建新目录
curl -X POST "http://your-showdoc-domain/server/index.php?s=/api/open/createCatalog" \
  -d "api_key=your_api_key" \
  -d "api_token=your_api_token" \
  -d "cat_name=数据库文档" \
  -d "parent_cat_id=0"  # 0表示顶级目录

3.2.3 获取目录树

# 获取项目目录结构
curl -X POST "http://your-showdoc-domain/server/index.php?s=/api/open/getCatalogTree" \
  -d "api_key=your_api_key" \
  -d "api_token=your_api_token"

3.3 三种实用开发场景

场景一：从Swagger文档自动导入API

import requests
import json

def import_from_swagger(api_key, api_token, swagger_json_path, base_url):
    # 读取Swagger JSON文件
    with open(swagger_json_path, 'r') as f:
        swagger_data = json.load(f)
    
    # 创建API目录
    catalog_response = requests.post(f"{base_url}/server/index.php?s=/api/open/createCatalog", 
                                    data={"api_key": api_key, "api_token": api_token, 
                                          "cat_name": "从Swagger导入的API"})
    cat_id = catalog_response.json().get('data', {}).get('cat_id')
    
    # 遍历Swagger文档，创建API页面
    for path, methods in swagger_data.get('paths', {}).items():
        for method, details in methods.items():
            page_title = f"{method.upper()} {path}"
            page_content = f"# {page_title}\n\n{details.get('description', '')}\n\n## 请求参数\n"
            
            # 添加请求参数描述
            if 'parameters' in details:
                for param in details['parameters']:
                    page_content += f"- {param.get('name')}: {param.get('description', '')} ({param.get('in')})\n"
            
            # 调用ShowDoc API创建页面
            requests.post(f"{base_url}/server/index.php?s=/api/open/updatePage",
                         data={"api_key": api_key, "api_token": api_token,
                               "page_title": page_title, "page_content": page_content,
                               "cat_id": cat_id})

# 使用示例
import_from_swagger("your_api_key", "your_api_token", "swagger.json", "http://your-showdoc-domain")

场景二：集成到GitLab CI/CD流程

在.gitlab-ci.yml中添加以下配置：

stages:
  - docs

update_docs:
  stage: docs
  script:
    - |
      # 从代码中提取文档内容
      php extract_docs.php > docs.md
      
      # 调用ShowDoc API更新文档
      curl -X POST "http://your-showdoc-domain/server/index.php?s=/api/open/updatePage" \
        -d "api_key=$SHOWDOC_API_KEY" \
        -d "api_token=$SHOWDOC_API_TOKEN" \
        -d "page_title=API文档" \
        -d "page_content=$(cat docs.md)"
  only:
    - master

场景三：数据库表结构自动生成文档

#!/bin/bash

# 数据库连接信息
DB_HOST="localhost"
DB_USER="root"
DB_PASS="password"
DB_NAME="your_database"

# ShowDoc API信息
API_KEY="your_api_key"
API_TOKEN="your_api_token"
SHOWDOC_URL="http://your-showdoc-domain/server/index.php?s=/api/open/updatePage"

# 创建数据库文档目录
CAT_ID=$(curl -s -X POST "$SHOWDOC_URL" -d "api_key=$API_KEY" -d "api_token=$API_TOKEN" -d "page_title=数据库结构" -d "page_content=## 数据库表结构" | jq -r '.data.cat_id')

# 获取所有表名
TABLES=$(mysql -h $DB_HOST -u $DB_USER -p$DB_PASS $DB_NAME -e "SHOW TABLES" | grep -v "Tables_in_")

# 遍历表，生成文档
for TABLE in $TABLES; do
  # 获取表结构
  TABLE_STRUCTURE=$(mysql -h $DB_HOST -u $DB_USER -p$DB_PASS $DB_NAME -e "DESCRIBE $TABLE" | awk 'NR>1 {print "- " $1 " (" $2 "): " $3}')
  
  # 生成Markdown内容
  CONTENT="# $TABLE 表结构\n\n$TABLE_STRUCTURE"
  
  # 调用ShowDoc API创建页面
  curl -s -X POST "$SHOWDOC_URL" -d "api_key=$API_KEY" -d "api_token=$API_TOKEN" -d "page_title=$TABLE" -d "page_content=$CONTENT" -d "cat_id=$CAT_ID" > /dev/null
  echo "Updated documentation for table: $TABLE"
done

⚠️ 注意事项：

1. API凭证应妥善保管，避免在代码中硬编码。
2. 对于频繁调用API的场景，应注意控制请求频率，避免给服务器带来过大负担。
3. 所有API调用都应包含错误处理逻辑，以应对网络问题或服务器错误。

四、场景拓展：ShowDoc API高级应用

4.1 构建自定义文档管理系统

通过ShowDoc API，你可以构建符合团队特定需求的文档管理系统。例如，可以创建一个内部工具，让产品经理直接在UI中编辑文档，然后通过API同步到ShowDoc。

4.2 实现多系统文档同步

如果你的团队使用多个系统管理不同类型的文档，可以通过ShowDoc API实现这些系统之间的文档同步。例如，将Confluence中的产品文档同步到ShowDoc中，供开发团队查看。

4.3 文档版本控制与审计

通过API记录每次文档更新的信息（谁、何时、做了什么更改），实现文档的版本控制和审计功能。这对于需要严格合规的行业尤为重要。

五、进阶技巧与常见问题

5.1 进阶使用技巧

技巧一：使用API批量迁移文档

当需要将大量文档从其他系统迁移到ShowDoc时，可以编写脚本批量调用API完成迁移。以下是一个简单的Python示例：

import requests
import os

def migrate_docs(api_key, api_token, source_dir, base_url):
    # 创建根目录
    root_response = requests.post(f"{base_url}/server/index.php?s=/api/open/createCatalog",
                                 data={"api_key": api_key, "api_token": api_token,
                                       "cat_name": "迁移文档"})
    root_cat_id = root_response.json().get('data', {}).get('cat_id')
    
    # 遍历目录结构
    for root, dirs, files in os.walk(source_dir):
        # 创建子目录
        relative_path = os.path.relpath(root, source_dir)
        if relative_path != '.':
            cat_response = requests.post(f"{base_url}/server/index.php?s=/api/open/createCatalog",
                                        data={"api_key": api_key, "api_token": api_token,
                                              "cat_name": os.path.basename(root),
                                              "parent_cat_id": root_cat_id})
            current_cat_id = cat_response.json().get('data', {}).get('cat_id')
        else:
            current_cat_id = root_cat_id
        
        # 处理Markdown文件
        for file in files:
            if file.endswith('.md'):
                with open(os.path.join(root, file), 'r') as f:
                    content = f.read()
                
                page_title = os.path.splitext(file)[0]
                requests.post(f"{base_url}/server/index.php?s=/api/open/updatePage",
                             data={"api_key": api_key, "api_token": api_token,
                                   "page_title": page_title, "page_content": content,
                                   "cat_id": current_cat_id})

# 使用示例
migrate_docs("your_api_key", "your_api_token", "/path/to/markdown/files", "http://your-showdoc-domain")

技巧二：实现API请求的缓存机制

对于频繁访问但不经常变化的文档，可以实现本地缓存机制，减少API调用次数，提高性能：

import requests
import json
import time
from datetime import datetime, timedelta

class ShowDocClient:
    def __init__(self, api_key, api_token, base_url, cache_dir='.showdoc_cache'):
        self.api_key = api_key
        self.api_token = api_token
        self.base_url = base_url
        self.cache_dir = cache_dir
        os.makedirs(cache_dir, exist_ok=True)
    
    def get_catalog_tree(self, cache_ttl=3600):
        """获取目录树，带缓存功能"""
        cache_file = os.path.join(self.cache_dir, 'catalog_tree.json')
        
        # 检查缓存是否有效
        if os.path.exists(cache_file):
            modified_time = os.path.getmtime(cache_file)
            if time.time() - modified_time < cache_ttl:
                with open(cache_file, 'r') as f:
                    return json.load(f)
        
        # 缓存无效，调用API获取
        response = requests.post(f"{self.base_url}/server/index.php?s=/api/open/getCatalogTree",
                                data={"api_key": self.api_key, "api_token": self.api_token})
        data = response.json()
        
        # 保存到缓存
        with open(cache_file, 'w') as f:
            json.dump(data, f)
        
        return data

5.2 常见问题解决方案

问题：API调用返回"权限不足"错误

解决方案：

1. 检查api_key和api_token是否正确。
2. 确认当前项目是否有使用API的权限。
3. 检查请求的IP是否在允许的IP列表中（如果设置了IP限制）。
4. 查看服务器日志，获取更详细的错误信息。

可以通过以下步骤排查：

# 1. 验证API凭证是否正确
curl -X POST "http://your-showdoc-domain/server/index.php?s=/api/open/getCatalogTree" \
  -d "api_key=your_api_key" \
  -d "api_token=your_api_token"

# 2. 检查服务器日志（需要服务器访问权限）
tail -f /path/to/showdoc/logs/error.log

如果凭证正确但仍然无法访问，可能是因为项目权限设置问题，需要联系ShowDoc管理员检查项目设置。

通过以上内容，相信你已经对ShowDoc API有了全面的了解。从基础集成到高级应用，ShowDoc API为文档自动化提供了强大的支持。无论是小型项目还是大型企业应用，都可以通过ShowDoc API构建高效、自动化的文档管理流程，让团队成员更专注于核心开发工作。