ドキュメント作成ツール

GitBook

概要

GitBookは現代的なドキュメント作成プラットフォームです。Git連携、API文書化、リアルタイム協働機能を統合し、技術チームの文書作成ワークフローを最適化します。

詳細

GitBook（ギットブック）は2014年に設立され、従来の文書作成ツールとソフトウェア開発ワークフローの隙間を埋めるソリューションとして急成長を遂げました。ブロックベースのWYSIWYGエディタにより、テキスト、コード、画像、API仕様書などを統合的に管理できます。Git同期機能により、開発チームはGitHubやGitLabのリポジトリと直接連携でき、マークダウンファイルの変更が自動的にドキュメントに反映されます。OpenAPI仕様書の自動インポート機能により、API文書化を大幅に効率化できます。分岐ベースのワークフローにより、コードレビューと同様の品質管理プロセスを文書作成に適用可能です。リアルタイム協働エディタにより、チームメンバーとの同時編集やコメント機能を活用できます。AI翻訳機能により多言語文書の作成と保守が効率化されます。2025年現在、技術文書、製品ガイド、API リファレンス、内部ナレッジベースなど幅広い用途で活用される包括的なドキュメンテーションプラットフォームです。

メリット・デメリット

メリット

• Git統合ワークフロー: GitHubやGitLabとの完全連携による開発者フレンドリーな文書管理
• API文書化の自動化: OpenAPI仕様書からインタラクティブな文書を自動生成
• リアルタイム協働: 同時編集、コメント、レビュー機能によるチーム作業効率化
• ブロックベースエディタ: コード、表、メディアを自由に組み合わせた文書作成
• AI翻訳機能: 多言語文書の作成と保守を自動化
• 分岐ベースワークフロー: コードレビューと同様の品質管理プロセス
• 豊富な統合機能: Slack、Figma、Notionなどとの連携

デメリット

• 料金体系: チーム利用時の月額費用負担
• 学習コスト: Git統合機能を活用するための技術知識が必要
• カスタマイズ制限: テーマやデザインのカスタマイズ自由度に制限
• オフライン機能: インターネット接続が必要な機能が多い
• エクスポート制約: 他ツールへの移行時のフォーマット制限

主要リンク

• GitBook公式サイト
• GitBookドキュメント
• API文書化ソリューション
• Git同期ガイド
• GitBook開発者API
• テンプレートギャラリー

書き方の例

基本的なドキュメント構造

# プロジェクトドキュメント

## 概要
このプロジェクトの基本説明

## API リファレンス

{% swagger method="get" path="/api/users" baseUrl="https://api.example.com" summary="ユーザー一覧取得" %}
{% swagger-description %}
登録されているユーザーの一覧を取得します。
{% endswagger-description %}

{% swagger-parameter in="query" name="page" type="integer" %}
ページ番号（デフォルト: 1）
{% endswagger-parameter %}

{% swagger-response status="200: OK" description="ユーザー一覧の取得に成功" %}
```json
{
  "users": [
    {
      "id": 1,
      "name": "田中太郎",
      "email": "[email protected]"
    }
  ],
  "pagination": {
    "page": 1,
    "total": 100
  }
}

{% endswagger-response %} {% endswagger %}

コードブロック

{% code title="app.js" overflow="wrap" lineNumbers="true" %}

const express = require('express');
const app = express();

app.get('/api/users', (req, res) => {
  const page = req.query.page || 1;
  // ユーザー一覧取得ロジック
  res.json({
    users: [], // 実際のユーザーデータ
    pagination: { page, total: 100 }
  });
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

{% endcode %}

### Git同期設定（.gitbook.yaml）
```yaml
# プロジェクトルート設定
root: ./docs/

# 文書構造定義
structure:
  readme: README.md
  summary: SUMMARY.md

# URL リダイレクト設定
redirects:
  old-api-docs: api/v2/reference.md
  legacy-guide: getting-started/new-guide.md

SUMMARY.mdによるナビゲーション構造

# Summary

## はじめに

* [プロジェクト概要](README.md)
* [クイックスタート](getting-started/quick-start.md)
  * [インストール](getting-started/installation.md)
  * [基本設定](getting-started/configuration.md)

## API リファレンス

* [認証](api/authentication.md)
* [ユーザー管理](api/users.md)
  * [ユーザー作成](api/users/create.md)
  * [ユーザー更新](api/users/update.md)
* [データ管理](api/data.md)

## 開発ガイド

* [アーキテクチャ](development/architecture.md)
* [コントリビューション](development/contributing.md)

OpenAPI仕様書の統合

openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: ユーザー管理システムのAPI仕様書

tags:
  - name: users
    description: ユーザー関連の操作
    x-page-title: "ユーザー管理"
    x-page-description: "ユーザーアカウントの作成、更新、削除機能"

paths:
  /users:
    get:
      tags:
        - users
      summary: ユーザー一覧取得
      description: 登録されているユーザーの一覧を取得
      parameters:
        - name: page
          in: query
          description: ページ番号
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
    post:
      tags:
        - users
      summary: ユーザー作成
      x-codeSamples:
        - lang: JavaScript
          label: Node.js SDK
          source: |
            const client = new UserClient({ apiKey: 'your-api-key' });
            
            const newUser = await client.users.create({
              name: '田中太郎',
              email: '[email protected]'
            });
            
            console.log('Created user:', newUser);

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          description: ユーザーID
        name:
          type: string
          description: ユーザー名
        email:
          type: string
          format: email
          description: メールアドレス

GitBook APIによる自動化

// GitBook APIを使用したチーム管理
const GITBOOK_API_KEY = process.env.GITBOOK_API_KEY;
const ORG_ID = 'your-org-id';

// ユーザーをチームに招待
async function inviteUser(email, role = 'read') {
  const response = await fetch("https://api.gitbook.com/v1/orgs/" + ORG_ID + "/invites", {
    method: 'POST',
    headers: {
      'Authorization': "Bearer " + GITBOOK_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      emails: [email],
      role: role,
      sso: true
    })
  });
  
  const result = await response.json();
  console.log('User invited:', result);
  return result;
}

// OpenAPI仕様書の更新
async function updateAPISpec(specName, openApiFile) {
  const { exec } = require('child_process');
  
  return new Promise((resolve, reject) => {
    exec("export GITBOOK_TOKEN=" + GITBOOK_API_KEY + " && gitbook openapi publish --spec " + specName + " --organization " + ORG_ID + " " + openApiFile, 
      (error, stdout, stderr) => {
        if (error) {
          reject(error);
        } else {
          resolve(stdout);
        }
      }
    );
  });
}

// 使用例
inviteUser('[email protected]', 'write');
updateAPISpec('main-api', './openapi.yaml');

訪問者認証による適応コンテンツ

// JWT生成による訪問者認証
import * as jose from 'jose';

const VISITOR_SIGNING_KEY = process.env.GITBOOK_VISITOR_SIGNING_KEY;

export async function generateVisitorToken(userInfo) {
  const claims = {
    firstName: userInfo.firstName,
    lastName: userInfo.lastName,
    role: userInfo.role,
    betaAccess: userInfo.betaAccess,
    products: userInfo.subscribedProducts
  };
  
  const jwt = await new jose.SignJWT(claims)
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('2h')
    .sign(new TextEncoder().encode(VISITOR_SIGNING_KEY));
    
  return jwt;
}

// Express.jsでの認証処理
app.post('/login', async (req, res) => {
  const user = await authenticateUser(req.body);
  const visitorToken = await generateVisitorToken(user);
  
  // GitBookにリダイレクト
  const docsUrl = "https://docs.company.com/?jwt_token=" + visitorToken;
  res.redirect(docsUrl);
});

Slackとの統合機能

<!-- Slackでの知識ベース検索 -->
/gitbook 認証エラーの解決方法を教えて

<!-- スレッドの内容をGitBookに保存 -->
@GitBook save

<!-- 公開Q&A -->
@GitBook APIの認証方法について教えて