GitBook
コラボレーションツール
GitBook
概要
GitBookは、技術文書・API文書作成に特化したコラボレーション・ドキュメント作成プラットフォームです。開発者フレンドリーなMarkdown編集、リアルタイムコラボレーション、Git統合による版数管理、OpenAPI仕様書の自動生成機能を提供。エンジニアリングチーム、プロダクトチーム、スタートアップでの技術文書作成において標準的地位を確立。2024-2025年にかけてリアルタイムコラボレーション強化、AI翻訳機能、OpenAPI改善、レビューシステム向上により、現代的な文書作成ワークフローを実現しています。
詳細
GitBook 2025年版は、技術文書作成における最前線のコラボレーションプラットフォームとして進化しています。WYSIWYG（What You See Is What You Get）エディタとMarkdown記法の完全サポートにより、エンジニアと非エンジニアの両方が効率的に文書作成可能。リアルタイムコラボレーション機能により複数のメンバーが同時編集でき、カラードカーソルとアバター表示により協働状況を可視化。Git統合（GitHub/GitLab）によるブランチベースワークフロー、変更要求システム、高度な権限管理により、大規模チームでの品質管理と協働体制を確立。2024年の主要アップデートにはOpenAPI仕様書の大幅改善、編集可能APIメソッドブロックの廃止、AI翻訳機能による多言語対応自動化、Scalarエンジンによる「試してみる」機能の強化が含まれます。開発者向けAPI、外部システム統合、カスタム機能拡張により、技術組織の文書化ワークフローを完全に最適化します。
主な特徴
- リアルタイムコラボレーション: 同時編集、カラードカーソル、アバター表示
- Git統合ワークフロー: GitHub/GitLab連携、ブランチベース編集
- OpenAPI自動生成: 仕様書からの自動ドキュメント生成とテスト機能
- Markdown＋WYSIWYG: 開発者フレンドリーな編集体験
- AI翻訳機能: 自動多言語対応とローカライゼーション
- 高度な権限管理: チーム別アクセス制御と承認フロー
メリット・デメリット
メリット
- 開発者とプロダクトチームの両方に最適化された編集体験
- Git統合による強力なバージョン管理と協働ワークフロー
- OpenAPI仕様書からの自動API文書生成とテスト機能
- リアルタイムコラボレーションによる効率的なチーム協働
- AI翻訳による多言語対応の自動化と工数削減
- 直感的なUI/UXによる学習コストの低さ
- スタートアップから大企業まで対応する段階的プライシング
- 豊富なインテグレーションと外部システム連携
デメリット
- 複雑な文書構造や大規模文書での表示パフォーマンス課題
- 高度なカスタマイズには技術的知識が必要
- エンタープライズ機能は高額な有料プランが必要
- オフライン編集機能の制限
- Git統合はパブリッシュ済みスペースでは利用不可
- 外部システムとの統合には開発作業が必要
- 移行時のデータエクスポート制限
- 日本語での高度な検索機能に制約
参考ページ
- GitBook 公式サイト
- GitBook Documentation
- GitBook API Reference
- GitBook OpenAPI Support
- GitBook GitHub Integration
- GitBook Pricing
書き方の例
基本設定とワークスペース作成
# GitBook基本セットアップ
# 1. GitBookアカウント作成: https://www.gitbook.com/
# 2. 組織（Organization）作成
# 3. スペース（Space）作成
# 4. Git統合設定（GitHub/GitLab）
# 5. チームメンバー招待と権限設定
# 基本的なスペース構造例
技術文書スペース/
├── Getting Started/
│ ├── Overview.md
│ ├── Installation.md
│ └── Quick Start.md
├── API Reference/
│ ├── Authentication.md
│ ├── Endpoints/
│ └── Error Handling.md
├── Guides/
│ ├── Best Practices/
│ ├── Tutorials/
│ └── FAQ.md
└── Changelog/
├── v2.0.0.md
├── v1.9.0.md
└── Archive/
# 推奨フォルダ構成（Git同期）
docs/
├── .gitbook.yaml
├── README.md
├── SUMMARY.md
├── getting-started/
├── api/
├── guides/
└── changelog/
GitBook API基本操作
// GitBook API基本設定
const GITBOOK_API_BASE = 'https://api.gitbook.com/v1';
const GITBOOK_TOKEN = process.env.GITBOOK_TOKEN;
class GitBookAPI {
constructor(token) {
this.token = token;
this.headers = {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
};
}
// 組織情報取得
async getOrganization(orgId) {
try {
const response = await fetch(`${GITBOOK_API_BASE}/orgs/${orgId}`, {
method: 'GET',
headers: this.headers,
});
if (!response.ok) {
throw new Error(`HTTP Error: ${response.status}`);
}
return await response.json();
} catch (error) {
console.error('組織情報取得エラー:', error);
throw error;
}
}
// スペース一覧取得
async getSpaces(orgId) {
try {
const response = await fetch(`${GITBOOK_API_BASE}/orgs/${orgId}/spaces`, {
method: 'GET',
headers: this.headers,
});
if (!response.ok) {
throw new Error(`HTTP Error: ${response.status}`);
}
return await response.json();
} catch (error) {
console.error('スペース一覧取得エラー:', error);
throw error;
}
}
// 新規ユーザー招待
async inviteUsers(orgId, emails, role = 'read', sso = true) {
try {
const response = await fetch(`${GITBOOK_API_BASE}/orgs/${orgId}/invites`, {
method: 'POST',
headers: this.headers,
body: JSON.stringify({
emails: emails,
role: role,
sso: sso,
}),
});
if (!response.ok) {
throw new Error(`HTTP Error: ${response.status}`);
}
return await response.json();
} catch (error) {
console.error('ユーザー招待エラー:', error);
throw error;
}
}
// チームメンバー管理
async manageTeamMembers(orgId, teamId, addEmails = [], removeEmails = []) {
try {
const response = await fetch(`${GITBOOK_API_BASE}/orgs/${orgId}/teams/${teamId}/members`, {
method: 'PUT',
headers: this.headers,
body: JSON.stringify({
add: addEmails,
remove: removeEmails,
}),
});
if (!response.ok) {
throw new Error(`HTTP Error: ${response.status}`);
}
return await response.json();
} catch (error) {
console.error('チームメンバー管理エラー:', error);
throw error;
}
}
// ユーザー削除
async removeUser(orgId, userId) {
try {
const response = await fetch(`${GITBOOK_API_BASE}/orgs/${orgId}/members/${userId}`, {
method: 'DELETE',
headers: this.headers,
});
if (!response.ok) {
throw new Error(`HTTP Error: ${response.status}`);
}
return true;
} catch (error) {
console.error('ユーザー削除エラー:', error);
throw error;
}
}
}
// 使用例
const gitbook = new GitBookAPI(GITBOOK_TOKEN);
// 組織のチーム管理例
async function manageOrganizationUsers() {
try {
const orgId = 'your-org-id';
// 新規ユーザー招待
const inviteResult = await gitbook.inviteUsers(
orgId,
['[email protected]', '[email protected]'],
'write',
true
);
console.log('招待完了:', inviteResult);
// チームメンバー追加・削除
const teamResult = await gitbook.manageTeamMembers(
orgId,
'team-id-123',
['[email protected]'],
['[email protected]']
);
console.log('チーム更新:', teamResult);
} catch (error) {
console.error('チーム管理エラー:', error);
}
}
Git統合と.gitbook.yaml設定
# .gitbook.yaml - GitBookとGitリポジトリの統合設定
# ルートディレクトリ設定
root: ./docs
# ドキュメント構造定義
structure:
readme: README.md
summary: SUMMARY.md
# リダイレクト設定
redirects:
help: support.md
guide: getting-started.md
# モノレポ対応の例
# packages/
# api/
# .gitbook.yaml
# README.md
# SUMMARY.md
# frontend/
# .gitbook.yaml
# README.md
# SUMMARY.md
# カスタム設定例（複数プロジェクト）
# Project A用設定
---
# パッケージ/api/.gitbook.yaml
root: ./
structure:
readme: README.md
summary: SUMMARY.md
redirects:
api-v1: legacy/api-v1.md
---
# パッケージ/frontend/.gitbook.yaml
root: ./
structure:
readme: README.md
summary: SUMMARY.md
redirects:
old-guide: archive/old-guide.md
OpenAPI統合とAPI文書自動生成
# GitBook CLI使用でのOpenAPI仕様書アップロード
export GITBOOK_TOKEN=your-api-token
# ローカルファイルをアップロード
gitbook openapi publish \
--spec api_spec_name \
--organization your_org_id \
./openapi.yaml
# ホストされているURLから更新
gitbook openapi publish \
--spec api_spec_name \
--organization your_org_id \
https://api.example.com/openapi.yaml
# 仕様書の強制更新（新リリース後など）
gitbook openapi publish \
--spec api_spec_name \
--organization your_org_id \
https://api.example.com/openapi.yaml \
--force
# OpenAPI仕様書でのGitBook拡張機能活用例
openapi: '3.0.3'
info:
title: Example API
version: '1.0.0'
description: GitBook統合API仕様書例
# ページ構造の制御
tags:
- name: users
x-page-title: "ユーザー管理"
x-page-description: "ユーザーアカウントとプロファイルの管理"
x-page-icon: "user"
description: |
ユーザー関連のすべての操作
{% raw %}
{% tabs %}
{% tab title="概要" %}
ユーザー管理APIの概要
{% endtab %}
{% tab title="認証" %}
認証方法の詳細
{% endtab %}
{% endtabs %}
{% endraw %}
- name: admin
x-parent: users # 階層化
paths:
/users:
get:
tags:
- users
summary: ユーザー一覧取得
description: システム内のユーザー一覧を取得します
x-stability: stable
x-codeSamples:
- lang: 'cURL'
label: 'CLI'
source: |
curl -L \
-H 'Authorization: Bearer <token>' \
'https://api.example.com/users'
- lang: 'JavaScript'
label: 'Node.js SDK'
source: |
import { createAPIClient } from 'example-api-sdk';
const client = createAPIClient({ apiKey: 'your-key' });
const users = await client.users.list();
console.log(users);
responses:
'200':
description: 成功
/users/{id}:
get:
tags:
- users
summary: ユーザー詳細取得
deprecated: true
x-deprecated-sunset: 2025-12-31
x-hideTryItPanel: true # テストパネル非表示
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: 成功
/internal/admin:
get:
summary: 内部管理者機能
x-internal: true # ドキュメントから非表示
responses:
'200':
description: 成功
components:
schemas:
UserStatus:
type: string
enum:
- ACTIVE
- INACTIVE
- PENDING
x-enumDescriptions:
ACTIVE: アクティブなユーザー
INACTIVE: 非アクティブなユーザー
PENDING: 承認待ちユーザー
リアルタイムコラボレーションとレビューワークフロー
# GitBookでの協働編集とレビュープロセス
## リアルタイムコラボレーション機能
- **同時編集**: 複数ユーザーによる同時編集が可能
- **アバター表示**: 編集中のユーザーのアバターがページ右上に表示
- **カラードカーソル**: 他のユーザーの編集位置がリアルタイムで表示
- **制限事項**: パブリッシュ済みスペースやGit同期有効時は利用不可
## 変更要求（Change Request）ワークフロー
1. **変更要求の作成**
- ドラフト変更を作成
- レビュアーを指定
- 変更理由とコメントを記載
2. **レビュープロセス**
- レビュアーによる内容確認
- コメントとフィードバック
- 承認または差し戻し
3. **マージ作業**
- 承認後のマージ実行
- 履歴の自動記録
- バージョン管理
## Git統合ワークフロー
```bash
# ブランチベースワークフロー例
# 新機能開発ブランチ作成
git checkout -b feature/api-documentation
git push -u origin feature/api-documentation
# GitBookでの編集
# 1. GitBookエディタで文書編集
# 2. 自動的にブランチに同期
# 3. コミット履歴が自動記録
# レビューとマージ
# 1. GitHub/GitLabでPull Request作成
# 2. コードレビューとGitBook変更確認
# 3. 承認後にマージ
git checkout main
git merge feature/api-documentation
git push origin main
# GitBookでの本番反映
# メインブランチマージ後、GitBookが自動的に更新
高度な機能とカスタマイズ
// GitBook適応的コンテンツ（Adaptive Content）設定
// 訪問者認証による動的コンテンツ表示
import * as jose from 'jose';
const GITBOOK_VISITOR_SIGNING_KEY = process.env.GITBOOK_VISITOR_SIGNING_KEY;
const GITBOOK_DOCS_URL = 'https://mycompany.gitbook.io/docs';
// ユーザー認証後のGitBook適応コンテンツ設定
export async function handleUserLogin(req, res) {
// ユーザー情報取得
const userInfo = await getUserInfo(req.user.id);
// GitBook向けクレーム作成
const gitbookClaims = {
firstName: userInfo.firstName,
lastName: userInfo.lastName,
role: userInfo.role,
isBetaUser: userInfo.isBetaUser,
products: userInfo.accessibleProducts,
featureFlags: await getFeatureFlags(req.user.id),
};
// JWT生成と署名
const gitbookVisitorJWT = await new jose.SignJWT(gitbookClaims)
.setProtectedHeader({ alg: 'HS256' })
.setIssuedAt()
.setExpirationTime('2h')
.sign(new TextEncoder().encode(GITBOOK_VISITOR_SIGNING_KEY));
// セッションCookieで設定（推奨）
res.cookie('gitbook-visitor-token', gitbookVisitorJWT, {
httpOnly: true,
secure: process.env.NODE_ENV === 'production',
maxAge: 2 * 60 * 60 * 1000, // 2時間
domain: '.example.com', // ワイルドカード設定
});
// または、URLパラメータで直接リダイレクト
const redirectURL = `${GITBOOK_DOCS_URL}/?jwt_token=${gitbookVisitorJWT}`;
res.redirect(redirectURL);
}
// 適応的コンテンツのスキーマ定義
const adaptiveContentSchema = {
type: "object",
properties: {
isBetaUser: {
type: "boolean",
description: "ベータユーザーかどうか"
},
role: {
type: "string",
enum: ["user", "admin", "developer"],
description: "ユーザーの役割"
},
products: {
type: "array",
items: { type: "string" },
description: "アクセス可能なプロダクト"
},
featureFlags: {
type: "object",
additionalProperties: { type: "boolean" },
description: "機能フラグ"
}
},
additionalProperties: false
};
// マルチテナント対応例
export async function handleMultiTenantAuth(req, res) {
const tenantId = req.query.tenant;
const tenantConfig = await getTenantConfig(tenantId);
const gitbookVisitorJWT = await new jose.SignJWT({
tenantId: tenantId,
tenantName: tenantConfig.name,
userRole: req.user.role,
})
.setProtectedHeader({ alg: 'HS256' })
.setIssuedAt()
.setExpirationTime('2h')
.sign(new TextEncoder().encode(tenantConfig.jwtSigningKey));
const redirectURL = `${tenantConfig.gitbookUrl}/${req.query.location || ''}?jwt_token=${gitbookVisitorJWT}`;
res.redirect(redirectURL);
}
AI翻訳とローカライゼーション自動化
# GitBook AI翻訳機能の活用
# 2024年に追加された自動翻訳機能
# 基本的な多言語設定
# 1. GitBookスペースで「Languages」設定を有効化
# 2. ソース言語（例：英語）とターゲット言語（日本語）を設定
# 3. AI翻訳の自動実行を設定
# 翻訳ワークフロー例
echo "原文更新 → AI自動翻訳 → レビュー → 公開"
# 手動翻訳実行（必要な場合）
# GitBook UI上で「Translate」ボタンクリック
# または変更検出時の自動翻訳実行
# 翻訳品質管理
echo "AI翻訳後の人的レビューを推奨"
echo "専門用語集の事前設定が翻訳品質向上に効果的"
<!-- GitBook適応的コンテンツ記述例 -->
# APIドキュメント
{% if visitor.isBetaUser %}
## ベータ機能
新しいAPI機能をお試しいただけます。
{% openapi-schemas spec="beta-api" schemas="BetaEndpoint" %}
ベータ版限定エンドポイント
{% endopenapi-schemas %}
{% endif %}
{% if "ENTERPRISE" in visitor.products %}
## エンタープライズ機能
高度なセキュリティとスケーラビリティ機能をご利用いただけます。
- SSO統合
- 高度な分析
- プレミアムサポート
{% endif %}
{% if visitor.role == "admin" %}
## 管理者向け情報
{% tabs %}
{% tab title="ユーザー管理" %}
ユーザー管理機能の詳細
{% endtab %}
{% tab title="システム設定" %}
システム設定の管理方法
{% endtab %}
{% endtabs %}
{% endif %}
## 基本機能
すべてのユーザーがご利用いただける基本機能です。