DifyでOpenAPI Swagger仕様を定義してJina Reader Toolを構築する方法

環境の準備

Difyプラットフォームでカスタムツールを作成する際、以下の手順でOpenAPI仕様を設定します。

API仕様の定義

サーバー設定の変更

ローカルDockerデプロイメント用にサーバーURLを指定します。

servers:
  - url: http://192.168.31.15:9001

完全なSwagger定義

openapi: 3.1.0
info:
  title: Reader Local Deployment API
  version: 1.1.0
  description: |
    Local deployment version of web content processor with screenshot capabilities.
    Converts web content to LLM-friendly formats and generates screenshots.
    
    Key Features:
    - Local Docker deployment
    - Multiple output formats support
    - Local screenshot storage
    - No authentication required
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: http://xxx.xxx.xxx.xxx:9001
    description: Local Docker deployment
  - url: https://reader.berlin.cx
    description: Public demo instance
paths:
  /{targetUrl}:
    get:
      operationId: processWebContent
      summary: Process web content from URL
      description: |
        Converts web content to specified format and optionally generates screenshots.
        Supported formats include raw text, markdown, HTML and various screenshot types.
      parameters:
        - in: path
          name: targetUrl
          required: true
          schema:
            type: string
            format: uri
            example: "https://github.com/intergalacticalvariable/reader/"
          description: |
            The full URL to process. Must be properly URL-encoded.
            Example value: `https%3A%2F%2Fgithub.com%2Fintergalacticalvariable%2Freader%2F`
          allowReserved: true
        - in: header
          name: X-Respond-With
          required: true
          schema:
            type: string
            enum: [text, markdown, html, screenshot, pageshot]
            default: text
          description: |
            Response format selector:
            - `text`: Clean text content (default)
            - `markdown`: Raw markdown output
            - `html`: Full page HTML
            - `screenshot`: Viewport-sized screenshot URL
            - `pageshot`: Full-page screenshot URL
      responses:
        '200':
          description: Successfully processed content
          content:
            text/plain:
              schema:
                oneOf:
                  - type: string
                    description: Text/markdown/HTML content
                    example: "This is cleaned text content..."
                  - type: string
                    format: uri
                    description: Local screenshot path
                    example: "/screenshots/20240501-142356_google.com.png"
            application/json:
              schema:
                type: object
                properties:
                  content:
                    oneOf:
                      - type: string
                        description: Text content
                      - type: object
                        properties:
                          screenshot_url:
                            type: string
                            format: uri
                            example: "/screenshots/fullpage_google.com.png"
                          screenshot_type:
                            type: string
                            enum: [viewport, fullpage]
                  processed_at:
                    type: string
                    format: date-time
                  source_url:
                    type: string
                    format: uri
        '400':
          description: Invalid URL format or unsupported response type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Content processing failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    Error:
      type: object
      properties:
        error_type:
          type: string
          enum: [invalid_url, processing_error, screenshot_error]
        message:
          type: string
          example: "Failed to capture screenshot"
        debug_info:
          type: string
          example: "Timeout waiting for page load"
      required: [error_type, message]

実装手順

1. Difyダッシュボードで「新規ツール」を選択
2. サーバーURLをローカル環境に変更
3. Swagger仕様として上記定義を貼り付け

テスト実行

テスト結果例：

まとめ

この方法で、Dify上でローカルデプロイメントのウェブコンテンツ処理ツールを簡単に作成できます。Swagger仕様の明確な定義により、APIの動作確認やドキュメンテーション作成が効率化されます。

---

参考記事：

• DifyをlocalなWebReaderと組み合わせてみるメモ。