AIエージェント活用ガイド

はじめに

APIドキュメントの作成と保守は、開発者にとって負担の大きい作業です。特に、複数のエンドポイントやパラメータが存在する場合、手動でのドキュメント作成はミスが発生しやすく、更新漏れが生じることも少なくありません。そこで注目されているのが、AIエージェントを活用したAPIドキュメントの自動生成です。本チュートリアルでは、Swagger（OpenAPI）形式の仕様書をAIエージェントが自動生成する方法を、具体的な手順とともに解説します。

前提条件

Python 3.8以上がインストールされていること

OpenAI APIキー（または他のLLM APIキー）を取得していること

基本的なPythonプログラミングの知識

ステップ1: 環境準備

まず、必要なライブラリをインストールします。

pip install openai pyyaml flask

openai: OpenAIのAPIを呼び出すため

pyyaml: OpenAPI仕様をYAML形式で出力するため

flask: サンプルAPIとして使用

ステップ2: サンプルAPIの作成

簡単なFlaskアプリケーションを作成します。

<h1>app.py</h1>
from flask import Flask, jsonify, request
app = Flask(__name__)
@app.route('/users', methods=['GET'])
def get_users():
    """ユーザー一覧を取得"""
    users = [
        {"id": 1, "name": "Alice"},
        {"id": 2, "name": "Bob"}
    ]
    return jsonify(users)
@app.route('/users', methods=['POST'])
def create_user():
    """新規ユーザーを作成"""
    data = request.get_json()
    return jsonify({"id": 3, "name": data["name"]}), 201
if __name__ == '__main__':
    app.run(debug=True)

ステップ3: AIエージェントによるドキュメント生成

AIエージェントにAPIのソースコードを読み込ませ、OpenAPI仕様を自動生成させます。以下のスクリプトでは、OpenAIのGPTモデルを使用しています。

<h1>generate_docs.py</h1>
import openai
import yaml
import json
openai.api_key = "your-api-key"
def generate_openapi_spec(source_code):
    prompt = f"""
    You are an AI assistant that generates OpenAPI 3.0 specification in YAML format from Python Flask source code.
    Given the following source code, generate a complete OpenAPI spec.
    Only output the YAML, no additional text.
Source code:
    {source_code}
    """
    response = openai.ChatCompletion.create(
        model="gpt-4",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": prompt}
        ],
        max_tokens=2000,
        temperature=0.2
    )
    return response.choices[0].message.content
if __name__ == "__main__":
    with open("app.py", "r") as f:
        code = f.read()
    spec_yaml = generate_openapi_spec(code)
    with open("openapi.yaml", "w") as f:
        f.write(spec_yaml)
    print("OpenAPI spec generated: openapi.yaml")

ステップ4: 生成結果の確認

生成されたopenapi.yamlを確認します。例えば、以下のような内容が出力されます。

openapi: "3.0.0"
info:
  title: Sample API
  version: "1.0.0"
paths:
  /users:
    get:
      summary: ユーザー一覧を取得
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: 新規ユーザーを作成
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: 作成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    CreateUserRequest:
      type: object
      properties:
        name:
          type: string

ステップ5: ドキュメントの可視化

生成したOpenAPI仕様をSwagger UIで表示するには、swagger-uiやredocなどのツールを使用します。簡単な例として、swagger-uiのDockerイメージを利用します。

docker run -p 8080:8080 -e SWAGGER_JSON=/app/openapi.yaml -v $(pwd):/app swaggerapi/swagger-ui

ブラウザでhttp://localhost:8080にアクセスすると、自動生成されたAPIドキュメントが表示されます。

応用: ソースコード変更時の自動更新

AIエージェントをCI/CDパイプラインに組み込むことで、ソースコード変更時に自動的にドキュメントを再生成できます。以下はGitHub Actionsの例です。

<h1>.github/workflows/update-docs.yml</h1>
name: Update API Docs
on:
  push:
    paths:
      - 'app.py'
jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.9'
      - name: Install dependencies
        run: pip install openai pyyaml
      - name: Generate OpenAPI spec
        run: python generate_docs.py
      - name: Commit and push
        run: |
          git config --global user.name 'github-actions'
          git config --global user.email 'github-actions@github.com'
          git add openapi.yaml
          git commit -m "Auto-update OpenAPI spec"
          git push

注意点とベストプラクティス

プロンプトの工夫: AIエージェントに正確なドキュメントを生成させるためには、プロンプトで出力形式や注意点を明確に指定します。

手動レビューの推奨: 生成されたドキュメントは必ず人間がレビューし、誤りがないか確認します。

コメントの活用: ソースコードに適切なdocstringやコメントを記述することで、AIがより正確に解釈できます。

セキュリティ: APIキーなどの機密情報をコードに直接記述しないように注意します。環境変数を使用しましょう。

まとめ

AIエージェントを活用することで、APIドキュメントの自動生成が効率的に行えます。本チュートリアルでは、FlaskアプリのソースコードからOpenAPI仕様を生成する方法を紹介しました。この手法を応用すれば、大規模なAPIでもドキュメントの更新が容易になり、開発者の負担を大幅に軽減できます。ぜひ、実際のプロジェクトで試してみてください。