name: readme-platform description: ReadMe.com平台集成，用于API文档管理。同步OpenAPI规范、管理版本、配置API参考设置、自动化更新日志，并与指标仪表板集成。 allowed-tools: Read, Write, Edit, Bash, Glob, Grep backlog-id: SK-012 metadata: author: babysitter-sdk version: “1.0.0”

ReadMe平台技能

ReadMe.com平台集成，用于API文档管理。

功能

将OpenAPI规范同步到ReadMe
管理文档版本
配置API参考设置
自定义页面管理
更新日志自动化
API指标仪表板集成
创建配方/教程
设置Webhook和自动化

使用场景

在以下情况下调用此技能：

将API文档部署到ReadMe
同步OpenAPI规范
管理版本化文档
配置API Explorer设置
设置更新日志自动化

输入参数

参数	类型	必填	描述
action	string	是	sync, version, page, changelog, metrics
apiKey	string	是	ReadMe API密钥
specPath	string	否	OpenAPI规范路径
version	string	否	文档版本
projectId	string	否	ReadMe项目ID

输入示例

{
  "action": "sync",
  "apiKey": "${README_API_KEY}",
  "specPath": "./api/openapi.yaml",
  "version": "1.0"
}

ReadMe CLI配置

.readme.yml

# ReadMe CLI配置
version: "1.0"
api:
  definition: ./api/openapi.yaml
  name: 我的API

changelogs:
  directory: ./changelogs

docs:
  directory: ./docs

categories:
  - slug: getting-started
    title: 入门指南
  - slug: api-reference
    title: API参考
  - slug: guides
    title: 指南

同步OpenAPI规范

使用rdme CLI

# 登录ReadMe
rdme login

# 同步OpenAPI规范
rdme openapi ./api/openapi.yaml --version=1.0

# 使用特定ID同步
rdme openapi ./api/openapi.yaml --id=abc123

# 同步前验证
rdme openapi:validate ./api/openapi.yaml

CI/CD集成

# .github/workflows/docs.yml
name: 同步API文档

on:
  push:
    branches: [main]
    paths:
      - 'api/openapi.yaml'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: 同步到ReadMe
        uses: readmeio/rdme@v8
        with:
          rdme: openapi ./api/openapi.yaml --key=${{ secrets.README_API_KEY }} --version=1.0

版本管理

创建版本

# 创建新版本
rdme versions:create 2.0 --fork=1.0

# 更新版本
rdme versions:update 2.0 --main=true

# 列出版本
rdme versions

版本配置

{
  "version": "2.0",
  "from": "1.0",
  "codename": "主要版本",
  "is_stable": true,
  "is_beta": false,
  "is_hidden": false,
  "is_deprecated": false
}

自定义页面

页面创建

# 创建文档页面
rdme docs ./docs --version=1.0

# 创建单个页面
rdme docs:single ./docs/getting-started.md --version=1.0

页面Frontmatter

---
title: 入门指南
slug: getting-started
category: 6123abc456def789
order: 1
hidden: false
---

# 入门指南

欢迎使用我们的API文档。

## 先决条件

- API密钥（从[仪表板](https://app.example.com)获取）
- Node.js 18+ 或 Python 3.9+

## 安装

[block:code]
{
  "codes": [
    {
      "code": "npm install @example/sdk",
      "language": "bash",
      "name": "npm"
    },
    {
      "code": "pip install example-sdk",
      "language": "bash",
      "name": "pip"
    }
  ]
}
[/block]

更新日志管理

更新日志条目

---
title: 版本2.0发布
type: added
hidden: false
createdAt: 2026-01-24
---

## 新功能

### OAuth 2.0支持
我们现在除了API密钥外还支持OAuth 2.0认证。

### 批量操作
新的批量端点，可在单个请求中处理多个项目。

## 改进

- 改进了速率限制，提供更好的错误消息
- 增强了Webhook可靠性

## 错误修复

- 修复了列表端点中的分页问题
- 解决了日期过滤器中的时区处理问题

同步更新日志

# 同步所有更新日志
rdme changelogs ./changelogs

# 同步单个更新日志
rdme changelogs:single ./changelogs/2.0-release.md

API Explorer配置

openapi.yaml增强

openapi: 3.1.0
info:
  title: 我的API
  version: 1.0.0
  x-readme:
    explorer-enabled: true
    proxy-enabled: true
    samples-enabled: true
    samples-languages:
      - curl
      - node
      - python
      - ruby

servers:
  - url: https://api.example.com/v1
    description: 生产环境
    x-readme:
      explorer-default: true

paths:
  /users:
    get:
      x-readme:
        code-samples:
          - language: javascript
            name: Node.js
            code: |
              const response = await fetch('https://api.example.com/v1/users', {
                headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
              });
        explorer-enabled: true

指标仪表板

API指标查询

# 通过API获取API指标
curl -X GET 'https://dash.readme.com/api/v1/api-metrics' \
  -H 'Authorization: Basic YOUR_API_KEY' \
  -H 'Content-Type: application/json'

指标响应

{
  "data": [
    {
      "endpoint": "GET /users",
      "requests": 15234,
      "success_rate": 99.2,
      "avg_latency": 145,
      "error_breakdown": {
        "400": 52,
        "401": 23,
        "500": 3
      }
    }
  ],
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-24"
  }
}

Webhooks

Webhook配置

{
  "url": "https://api.example.com/readme-webhook",
  "events": [
    "doc.created",
    "doc.updated",
    "changelog.created",
    "api_spec.uploaded"
  ],
  "secret": "your-webhook-secret"
}

Webhook处理器

app.post('/readme-webhook', (req, res) => {
  const signature = req.headers['x-readme-signature'];

  // 验证签名
  if (!verifySignature(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('无效签名');
  }

  const { event, doc, project } = req.body;

  switch (event) {
    case 'doc.updated':
      console.log(`文档更新: ${doc.title}`);
      break;
    case 'api_spec.uploaded':
      console.log('API规范已更新');
      break;
  }

  res.status(200).send('OK');
});

自定义区块

交互式代码示例

[block:code]
{
  "codes": [
    {
      "code": "const client = new Client({ apiKey: 'YOUR_KEY' });
const users = await client.users.list();",
      "language": "javascript",
      "name": "JavaScript"
    },
    {
      "code": "client = Client(api_key='YOUR_KEY')
users = client.users.list()",
      "language": "python",
      "name": "Python"
    }
  ]
}
[/block]

提示区块

[block:callout]
{
  "type": "info",
  "title": "速率限制",
  "body": "此端点每分钟限制100个请求。"
}
[/block]

[block:callout]
{
  "type": "warning",
  "title": "弃用通知",
  "body": "此端点将在版本3.0中移除。"
}
[/block]

工作流程

配置项目 - 设置ReadMe项目配置
同步OpenAPI - 上传/更新API规范
创建页面 - 编写自定义文档
配置Explorer - 设置API Explorer
添加更新日志 - 记录版本变更
设置Webhooks - 启用自动化

依赖项

{
  "devDependencies": {
    "rdme": "^9.0.0"
  }
}

CLI命令

# 安装CLI
npm install -g rdme

# 登录
rdme login

# 同步OpenAPI规范
rdme openapi ./api/openapi.yaml --version=1.0

# 同步文档
rdme docs ./docs --version=1.0

# 创建版本
rdme versions:create 2.0 --fork=1.0

# 同步更新日志
rdme changelogs ./changelogs

最佳实践

随版本发布文档
使用更新日志记录发布说明
为所有端点配置代码示例
启用API Explorer进行测试
设置Webhooks实现自动化
使用自定义区块丰富内容

参考资料

ReadMe: https://readme.com/
rdme CLI: https://github.com/readmeio/rdme
ReadMe API: https://docs.readme.com/reference
OpenAPI扩展: https://docs.readme.com/docs/openapi-extensions

目标流程

api-doc-generation.js
api-reference-docs.js
docs-versioning.js