Making Your APIs Visible Using Capabilities for GitHub 7 GitBook Discovery and Documentation

Your organization has more APIs than anyone thinks. Specs are scattered across GitHub repos. Docs exist in GitBook spaces that were created for a launch and never updated. Some APIs have specs but no docs. Others have docs but no specs. A handful have neither.

This is the API visibility problem, and it's universal. GitHub and GitBook are both excellent platforms. The gap is the workflow between them.

Capabilities

Naftiko capabilities — each a portable YAML file that consumes the GitHub and/or GitBook APIs and exposes MCP tools for the workflows that documentation writers and governance teams need. No code generation, no SDK, no platform subscription.

Discovery

Helping you with your API discovery.

• GitHub OpenAPI Scanner — scans every repo in a GitHub org for OpenAPI/AsyncAPI specs
• GitBook Space Auditor — checks spaces for completeness, staleness, missing descriptions
• API Documentation Gap Analyzer — compares GitHub specs vs GitBook docs, finds gaps in both directions
• Documentation Coverage Scorer — measures what percentage of API operations are documented

Here's the scanner:

naftiko: "0.5"
info:
  label: "GitHub OpenAPI Scanner"
  description: "Scans GitHub organization repositories for OpenAPI and AsyncAPI specification files, building an inventory of every API definition across the org."
capability:
  exposes:
    - type: "mcp"
      namespace: "spec-scanner"
      tools:
        - name: "scan-org-for-specs"
          description: "Scans all repositories in a GitHub organization for OpenAPI and AsyncAPI specification files."
          inputParameters:
            - name: org
              in: query
              type: string
          steps:
            - name: search-openapi
              type: call
              call: "github.search-code"
              with:
                q: "org:{{org}} filename:openapi"
                per_page: 100
            - name: search-asyncapi
              type: call
              call: "github.search-code"
              with:
                q: "org:{{org}} filename:asyncapi"
                per_page: 100
  consumes:
    - namespace: "github"
      type: "http"
      baseUri: "https://api.github.com"
      authentication:
        type: "bearer"
        token: "{{github_token}}"
      inputParameters:
        - name: "github_token"
          in: "environment"
        - name: "Accept"
          in: "header"
          value: "application/vnd.github+json"
        - name: "X-GitHub-Api-Version"
          in: "header"
          value: "2022-11-28"
      resources:
        - name: "code-search"
          label: "Code Search"
          description: "Search for code across repositories"
          path: "/search/code"
          operations:
            - name: "search-code"
              method: "GET"
              label: "Search Code"

And here's the gap analyzer that compares both platforms:

naftiko: "0.5"
info:
  label: "API Documentation Gap Analyzer"
  description: "Compares API specifications discovered on GitHub against documentation published in GitBook to identify undocumented APIs and orphaned docs."
capability:
  exposes:
    - type: "mcp"
      namespace: "gap-analyzer"
      tools:
        - name: "compare-specs-to-docs"
          description: "Searches GitHub for API specs and GitBook for documentation spaces, then compares the two to identify gaps."
          inputParameters:
            - name: org
              in: query
              type: string
            - name: gitbook_orgId
              in: query
              type: string
          steps:
            - name: find-github-specs
              type: call
              call: "github.search-code"
              with:
                q: "org:{{org}} filename:openapi"
                per_page: 100
            - name: find-gitbook-spaces
              type: call
              call: "gitbook.list-spaces"
              with:
                orgId: "{{gitbook_orgId}}"
  consumes:
    - namespace: "github"
      type: "http"
      baseUri: "https://api.github.com"
      authentication:
        type: "bearer"
        token: "{{github_token}}"
      inputParameters:
        - name: "github_token"
          in: "environment"
        - name: "Accept"
          in: "header"
          value: "application/vnd.github+json"
      resources:
        - name: "code-search"
          label: "Code Search"
          path: "/search/code"
          operations:
            - name: "search-code"
              method: "GET"
              label: "Search Code"
    - namespace: "gitbook"
      type: "http"
      baseUri: "https://api.gitbook.com/v1"
      authentication:
        type: "bearer"
        token: "{{gitbook_token}}"
      inputParameters:
        - name: "gitbook_token"
          in: "environment"
      resources:
        - name: "org-spaces"
          label: "Organization Spaces"
          path: "/orgs/{{orgId}}/spaces"
          inputParameters:
            - name: "orgId"
              in: "path"
          operations:
            - name: "list-spaces"
              method: "GET"
              label: "List Spaces"

GitHub → GitBook

Keeping your repos in alignment with what teams do in Gitbook.

• GitHub-to-GitBook Spec Publisher — fetches specs from GitHub, creates GitBook spaces
• API Catalog Publisher — aggregates multi-repo specs into a browsable GitBook collection
• OpenAPI GitBook Uploader — uploads specs to GitBook's native interactive API viewer
• API Changelog Publisher — generates changelogs from spec diffs, publishes to GitBook

Here's the publisher capabilty:

naftiko: "0.5"
info:
  label: "GitHub-to-GitBook Spec Publisher"
  description: "Discovers OpenAPI specifications in GitHub repositories and publishes them as structured documentation in GitBook spaces."
capability:
  exposes:
    - type: "mcp"
      namespace: "spec-publisher"
      tools:
        - name: "publish-spec-to-gitbook"
          description: "Fetches an OpenAPI spec from a GitHub repo and creates or updates a GitBook space with the spec content."
          inputParameters:
            - name: owner
              in: query
              type: string
            - name: repo
              in: query
              type: string
            - name: spec_path
              in: query
              type: string
            - name: gitbook_orgId
              in: query
              type: string
            - name: space_title
              in: query
              type: string
          steps:
            - name: fetch-spec
              type: call
              call: "github.get-file-contents"
              with:
                owner: "{{owner}}"
                repo: "{{repo}}"
                file_path: "{{spec_path}}"
            - name: create-space
              type: call
              call: "gitbook.create-space"
              with:
                orgId: "{{gitbook_orgId}}"
                title: "{{space_title}}"
                visibility: "public"
        - name: "batch-publish-org-specs"
          description: "Scans a GitHub org for all OpenAPI specs and publishes each to a GitBook space."
          inputParameters:
            - name: org
              in: query
              type: string
            - name: gitbook_orgId
              in: query
              type: string
          steps:
            - name: find-specs
              type: call
              call: "github.search-code"
              with:
                q: "org:{{org}} filename:openapi"
                per_page: 100
            - name: list-existing
              type: call
              call: "gitbook.list-spaces"
              with:
                orgId: "{{gitbook_orgId}}"
  consumes:
    - namespace: "github"
      type: "http"
      baseUri: "https://api.github.com"
      authentication:
        type: "bearer"
        token: "{{github_token}}"
      inputParameters:
        - name: "github_token"
          in: "environment"
        - name: "Accept"
          in: "header"
          value: "application/vnd.github+json"
      resources:
        - name: "repo-contents"
          label: "Repository File Contents"
          path: "/repos/{{owner}}/{{repo}}/contents/{{file_path}}"
          inputParameters:
            - name: "owner"
              in: "path"
            - name: "repo"
              in: "path"
            - name: "file_path"
              in: "path"
          operations:
            - name: "get-file-contents"
              method: "GET"
              label: "Get File Contents"
        - name: "code-search"
          label: "Code Search"
          path: "/search/code"
          operations:
            - name: "search-code"
              method: "GET"
              label: "Search Code"
    - namespace: "gitbook"
      type: "http"
      baseUri: "https://api.gitbook.com/v1"
      authentication:
        type: "bearer"
        token: "{{gitbook_token}}"
      inputParameters:
        - name: "gitbook_token"
          in: "environment"
      resources:
        - name: "org-spaces"
          label: "Organization Spaces"
          path: "/orgs/{{orgId}}/spaces"
          inputParameters:
            - name: "orgId"
              in: "path"
          operations:
            - name: "list-spaces"
              method: "GET"
              label: "List Spaces"
            - name: "create-space"
              method: "POST"
              label: "Create Space"
        - name: "openapi-specs"
          label: "OpenAPI Specs"
          path: "/spaces/{{spaceId}}/openapi"
          inputParameters:
            - name: "spaceId"
              in: "path"
          operations:
            - name: "upload-openapi"
              method: "POST"
              label: "Upload OpenAPI Spec"

GitBook → GitHub

Now let's go back the other way from GitHub to Gitbook.

• GitBook-to-GitHub Spec Centralizer — extracts docs from GitBook, commits to a central GitHub repo
• Multi-Repo Spec Consolidator — consolidates scattered specs into one canonical repo

Governance

Now you can govern things because you know where the APIs are.

• GitBook-GitHub Doc Sync — bi-directional sync, detects drift
• API Doc Freshness Monitor — flags stale documentation before consumers notice
• GitBook Change Request Reviewer — PR-style review for documentation updates
• GitBook Collection Organizer — organizes spaces into domain-based collections
• API Style Guide Enforcer — validates docs against style guidelines, creates fix requests
• GitBook Search Indexer — cross-space search, duplicate detection

Here's the style guide enforcer — it searches for banned terms and creates change requests for fixes:

naftiko: "0.5"
info:
  label: "API Style Guide Enforcer"
  description: "Validates API documentation in GitBook against organizational style guidelines."
capability:
  exposes:
    - type: "mcp"
      namespace: "style-enforcer"
      tools:
        - name: "search-for-banned-terms"
          description: "Searches for terminology that violates the style guide."
          inputParameters:
            - name: gitbook_orgId
              in: query
              type: string
            - name: banned_term
              in: query
              type: string
          steps:
            - name: search-content
              type: call
              call: "gitbook.search-content"
              with:
                orgId: "{{gitbook_orgId}}"
                query: "{{banned_term}}"
        - name: "create-style-fix-request"
          description: "Creates a change request to track a style violation fix."
          inputParameters:
            - name: spaceId
              in: query
              type: string
            - name: violation_summary
              in: query
              type: string
            - name: fix_description
              in: query
              type: string
          steps:
            - name: create-cr
              type: call
              call: "gitbook.create-change-request"
              with:
                spaceId: "{{spaceId}}"
                subject: "{{violation_summary}}"
                description: "{{fix_description}}"
  consumes:
    - namespace: "gitbook"
      type: "http"
      baseUri: "https://api.gitbook.com/v1"
      authentication:
        type: "bearer"
        token: "{{gitbook_token}}"
      inputParameters:
        - name: "gitbook_token"
          in: "environment"
      resources:
        - name: "search"
          label: "Search"
          path: "/orgs/{{orgId}}/search"
          inputParameters:
            - name: "orgId"
              in: "path"
          operations:
            - name: "search-content"
              method: "GET"
              label: "Search Content"
        - name: "change-requests"
          label: "Change Requests"
          path: "/spaces/{{spaceId}}/change-requests"
          inputParameters:
            - name: "spaceId"
              in: "path"
          operations:
            - name: "create-change-request"
              method: "POST"
              label: "Create Change Request"

How it works

I am not sure how you organization operates, and I tried to cover the bases.

Each capability is a Naftiko 0.5 YAML file that declares:

• What APIs it consumes (GitHub, GitBook, or both)
• What MCP tools it exposes*

All you do is point the Naftiko Framework at the YAML, and it serves live MCP tools, agent skills, and REST endpoints. The YAML is the runtime — no code generation required.

Why capabilities for this

The individual API calls are simple. The hard part is doing them consistently, across every repo and every space, over time. Manual processes don't scale. One-time audits go stale. Documentation sprints easily get deprioritized.

Capabilities make the workflow repeatable. Run them on a schedule, wire them into your CI, or invoke the MCP tools from an agent. The more alignment you can bring, the more likely you'll be governing the right things. You can't govern what you don't see.