API 文档站
本教程介绍如何为 API 或 SDK 创建专业的文档站点。
项目结构
api-docs/
├── docs/
│ ├── .vitepress/
│ │ └── config.mts
│ ├── api/
│ │ ├── authentication.md
│ │ ├── users.md
│ │ └── products.md
│ ├── guide/
│ │ ├── getting-started.md
│ │ └── errors.md
│ └── index.md
└── openapi.yaml # OpenAPI 规范文件配置文件
ts
// docs/.vitepress/config.mts
import { defineConfig } from 'vitepress'
export default defineConfig({
title: 'API 文档',
description: 'REST API 参考文档',
themeConfig: {
logo: '/logo.svg',
nav: [
{ text: '指南', link: '/guide/getting-started' },
{ text: 'API 参考', link: '/api/authentication' },
{ text: 'Changelog', link: '/changelog' }
],
sidebar: {
'/guide/': [
{
text: '入门指南',
items: [
{ text: '快速开始', link: '/guide/getting-started' },
{ text: '认证', link: '/guide/authentication' },
{ text: '错误处理', link: '/guide/errors' },
{ text: '速率限制', link: '/guide/rate-limits' }
]
}
],
'/api/': [
{
text: 'API 参考',
items: [
{ text: '认证', link: '/api/authentication' },
{ text: '用户', link: '/api/users' },
{ text: '产品', link: '/api/products' },
{ text: '订单', link: '/api/orders' }
]
}
]
},
search: {
provider: 'algolia',
options: {
appId: 'YOUR_APP_ID',
apiKey: 'YOUR_API_KEY',
indexName: 'api-docs'
}
}
}
})API 文档模板
端点文档格式
markdown
---
title: 用户 API
description: 用户相关的 API 端点
---
# 用户 API
用户资源的创建、查询、更新和删除操作。
## 获取用户列表
获取所有用户的分页列表。
### 请求
`GET /api/v1/users`
### 参数
| 参数 | 类型 | 位置 | 必填 | 说明 |
|------|------|------|------|------|
| page | integer | query | 否 | 页码，默认 1 |
| limit | integer | query | 否 | 每页数量，默认 20 |
| status | string | query | 否 | 状态筛选 |
### 示例请求
\`\`\`bash
curl -X GET "https://api.example.com/api/v1/users" \
-H "Authorization: Bearer YOUR_TOKEN"
\`\`\`
### 响应
\`\`\`json
{
"data": [
{
"id": 1,
"name": "张三",
"email": "zhangsan@example.com",
"status": "active",
"created_at": "2024-01-15T10:30:00Z"
}
],
"meta": {
"total": 100,
"page": 1,
"limit": 20
}
}
\`\`\`
### 响应状态码
| 状态码 | 说明 |
|--------|------|
| 200 | 成功 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 429 | 请求过多 |
---
## 创建用户
创建一个新用户。
### 请求
`POST /api/v1/users`
### 请求体
\`\`\`json
{
"name": "张三",
"email": "zhangsan@example.com",
"password": "secure_password"
}
\`\`\`
### 参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 用户名，2-50字符 |
| email | string | 是 | 邮箱地址 |
| password | string | 是 | 密码，至少8位 |
### 示例请求
\`\`\`bash
curl -X POST "https://api.example.com/api/v1/users" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "张三",
"email": "zhangsan@example.com",
"password": "secure_password"
}'
\`\`\`
### 响应
\`\`\`json
{
"id": 1,
"name": "张三",
"email": "zhangsan@example.com",
"status": "active",
"created_at": "2024-01-15T10:30:00Z"
}
\`\`\`代码示例组件
创建多语言代码示例：
vue
<!-- docs/.vitepress/theme/components/CodeExample.vue -->
<script setup>
import { ref } from 'vue'
const props = defineProps({
endpoint: String,
method: String
})
const languages = ['bash', 'javascript', 'python', 'go']
const selected = ref('bash')
const baseUrl = 'https://api.example.com'
</script>
<template>
<div class="code-example">
<div class="tabs">
<button
v-for="lang in languages"
:key="lang"
:class="{ active: selected === lang }"
@click="selected = lang"
>
{{ lang }}
</button>
</div>
<div class="code-content">
<slot :name="selected" />
</div>
</div>
</template>错误码文档
markdown
---
title: 错误处理
description: API 错误响应格式和错误码说明
---
# 错误处理
API 返回的错误遵循统一格式。
## 错误响应格式
\`\`\`json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "请求参数验证失败",
"details": [
{
"field": "email",
"message": "邮箱格式不正确"
}
]
}
}
\`\`\`
## 错误码列表
### 通用错误 (1xxx)
| 错误码 | 说明 | HTTP 状态码 |
|--------|------|-------------|
| 1001 | 参数验证失败 | 400 |
| 1002 | 请求格式错误 | 400 |
| 1003 | 资源不存在 | 404 |
### 认证错误 (2xxx)
| 错误码 | 说明 | HTTP 状态码 |
|--------|------|-------------|
| 2001 | 未提供认证信息 | 401 |
| 2002 | Token 无效 | 401 |
| 2003 | Token 已过期 | 401 |
| 2004 | 权限不足 | 403 |
### 业务错误 (3xxx)
| 错误码 | 说明 | HTTP 状态码 |
|--------|------|-------------|
| 3001 | 用户已存在 | 409 |
| 3002 | 余额不足 | 400 |
| 3003 | 库存不足 | 400 |SDK 文档集成
JavaScript SDK
markdown
## 安装
\`\`\`bash
npm install @example/sdk
\`\`\`
## 初始化
\`\`\`javascript
import { ExampleClient } from '@example/sdk'
const client = new ExampleClient({
apiKey: 'your-api-key',
baseUrl: 'https://api.example.com'
})
\`\`\`
## 使用示例
\`\`\`javascript
// 获取用户列表
const users = await client.users.list({
page: 1,
limit: 20
})
// 创建用户
const user = await client.users.create({
name: '张三',
email: 'zhangsan@example.com'
})
\`\`\`最佳实践
| 实践 | 说明 |
|---|---|
| 统一格式 | 所有 API 使用一致的文档结构 |
| 完整示例 | 提供可直接运行的代码 |
| 错误说明 | 详细说明可能的错误 |
| 版本管理 | 明确 API 版本信息 |
| 交互体验 | 提供在线测试功能 |
下一步
查看 个人简历站 学习搭建个人简历站点。
🎯 进阶挑战
完成基础教程后，尝试以下挑战来提升你的技能：
挑战 1：在线 API 测试工具 ⭐⭐⭐⭐
目标：在文档中嵌入可交互的 API 测试工具。
提示：
- 创建请求表单组件
- 处理跨域请求（使用代理或 CORS）
- 展示响应结果和状态码
参考思路：
vue
<script setup>
const response = ref(null)
const loading = ref(false)
async function sendRequest() {
loading.value = true
try {
const res = await fetch(endpoint, { method, headers, body })
response.value = await res.json()
} finally {
loading.value = false
}
}
</script>挑战 2：OpenAPI 自动文档 ⭐⭐⭐⭐
目标：从 OpenAPI/Swagger 规范文件自动生成文档。
提示：
- 解析 OpenAPI YAML/JSON 文件
- 自动生成端点文档
- 提取请求/响应示例
挑战 3：API 变更日志 ⭐⭐⭐
目标：自动生成 API 版本变更日志。
提示：
- 记录 API 版本历史
- 对比版本差异
- 标记废弃接口
挑战 4：SDK 代码生成器 ⭐⭐⭐⭐⭐
目标：根据 API 文档自动生成多语言 SDK 代码。
提示：
- 解析 API 定义
- 使用模板生成代码
- 支持多种语言（JS、Python、Go）
挑战 5：API 健康检查面板 ⭐⭐⭐
目标：创建 API 端点健康状态监控面板。
提示：
- 定时发送健康检查请求
- 记录响应时间
- 可视化展示状态
挑战 6：请求示例多语言切换 ⭐⭐
目标：为每个 API 端点提供多种编程语言的请求示例。
提示：
- 创建代码模板
- 实现语言切换标签
- 保持参数一致性