Every enterprise has more APIs than it thinks it does. That is not a hot take — it is a structural reality of how organizations build software. Teams create APIs, commit specs to their repos, sometimes write documentation, and move on. Over time the distance between the spec in the repo and the documentation on the platform widens until they describe different things, or one of them stops existing entirely.
The result is an API visibility problem that compounds quietly. New developers cannot find what already exists. Governance teams cannot assess what is documented and what is not. Consumers encounter stale docs and lose trust in the platform. Duplicate APIs get built because nobody knew the first one existed.
This is not a tooling gap. GitHub is an excellent place to store API specifications. GitBook is an excellent place to publish API documentation. The gap is in the workflows between them — the discovery, publishing, syncing, auditing, and review workflows that keep specs and docs in alignment over time. Those workflows are manual in most organizations, which means they are inconsistent, incomplete, and the first thing to be deprioritized when deadlines hit.
Sixteen Capabilities for API Discovery and Documentation
We built a collection of sixteen Naftiko capabilities that consume the GitHub and GitBook APIs and expose MCP tools for the workflows that documentation writers and API governance teams actually need. Every capability is a portable Naftiko 0.5 YAML file that anyone can run using the open-source Naftiko Fleet.
The collection covers four workflow categories.
Discovery and Inventory
The first step is knowing what you have. The GitHub OpenAPI Scanner scans every repository in a GitHub organization for OpenAPI and AsyncAPI specification files, building a complete inventory of API definitions across the org.
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
- name: "get-spec-contents"
description: "Retrieves the raw contents of a discovered spec file from a GitHub repository."
inputParameters:
- name: owner
in: query
type: string
- name: repo
in: query
type: string
- name: file_path
in: query
type: string
steps:
- name: fetch-file
type: call
call: "github.get-file-contents"
with:
owner: "{{owner}}"
repo: "{{repo}}"
file_path: "{{file_path}}"
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"
path: "/search/code"
operations:
- name: "search-code"
method: "GET"
label: "Search Code"
- 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"
The GitBook Space Auditor checks every GitBook space for completeness — missing descriptions, empty pages, outdated content, inconsistent structure. The API Documentation Gap Analyzer compares the two: which specs on GitHub have no corresponding GitBook documentation? Which GitBook spaces have no backing spec? The Documentation Coverage Scorer goes deeper, measuring what percentage of an API’s operations are actually documented, producing a per-API and org-wide coverage score that governance teams can track over time.
These four capabilities together answer the question that every API governance program needs answered first: what do we have, what is documented, and where are the gaps?
GitHub to GitBook
Once you know what exists, the next step is publishing. The GitHub-to-GitBook Spec Publisher fetches OpenAPI specs from GitHub repos and creates corresponding GitBook spaces with the spec content.
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: "upload-openapi-to-space"
description: "Uploads an OpenAPI specification to GitBook's native spec viewer within an existing space."
inputParameters:
- name: spaceId
in: query
type: string
- name: spec_url
in: query
type: string
steps:
- name: upload-spec
type: call
call: "gitbook.upload-openapi"
with:
spaceId: "{{spaceId}}"
url: "{{spec_url}}"
source: "url"
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"
The API Catalog Publisher aggregates specs from multiple repos and publishes a browsable catalog as a GitBook collection — one place for consumers to discover every API. The OpenAPI GitBook Uploader takes advantage of GitBook’s native OpenAPI rendering, uploading specs directly to the interactive API reference viewer so consumers get try-it-out functionality without manual page creation. The API Changelog Publisher detects changes between spec versions in GitHub commits and publishes human-readable changelogs to GitBook so consumers know what changed before their integrations break.
GitBook to GitHub
Not every team starts with a spec. Some teams author documentation directly in GitBook — particularly product teams, partner-facing API teams, and teams that practice documentation-first design. The GitBook-to-GitHub Spec Centralizer extracts content from GitBook spaces and commits it to a centralized GitHub repository, ensuring those documentation-first APIs are version-controlled and visible to governance tooling.
naftiko: "0.5"
info:
label: "GitBook-to-GitHub Spec Centralizer"
description: "Extracts API documentation and specifications from GitBook spaces and commits them to a centralized GitHub repository."
capability:
exposes:
- type: "mcp"
namespace: "spec-centralizer"
tools:
- name: "extract-specs-from-gitbook"
description: "Lists all GitBook spaces and identifies those containing API documentation."
inputParameters:
- name: gitbook_orgId
in: query
type: string
steps:
- name: list-spaces
type: call
call: "gitbook.list-spaces"
with:
orgId: "{{gitbook_orgId}}"
- name: "commit-spec-to-github"
description: "Commits extracted spec content to a centralized GitHub repository."
inputParameters:
- name: owner
in: query
type: string
- name: repo
in: query
type: string
- name: file_path
in: query
type: string
- name: content
in: query
type: string
- name: commit_message
in: query
type: string
steps:
- name: push-file
type: call
call: "github.push-file"
with:
owner: "{{owner}}"
repo: "{{repo}}"
file_path: "{{file_path}}"
content: "{{content}}"
commit_message: "{{commit_message}}"
branch: "main"
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: "org-spaces"
label: "Organization Spaces"
path: "/orgs/{{orgId}}/spaces"
inputParameters:
- name: "orgId"
in: "path"
operations:
- name: "list-spaces"
method: "GET"
label: "List Spaces"
- name: "space-content"
label: "Space Content"
path: "/spaces/{{spaceId}}/content"
inputParameters:
- name: "spaceId"
in: "path"
operations:
- name: "get-content"
method: "GET"
label: "Get Space Content"
- 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: "push-file"
method: "PUT"
label: "Push File"
The Multi-Repo Spec Consolidator solves the adjacent problem of specs scattered across dozens of repos with inconsistent naming and structure. It discovers specs across an organization and consolidates them into a single canonical repository with a consistent directory structure, making downstream tooling like linters, portals, and SDK generators reliable.
Sync and Governance
Visibility is not a one-time project. Documentation drifts. Specs get updated without corresponding doc updates. New pages get published without review. The remaining six capabilities address the ongoing governance workflows that keep documentation trustworthy over time.
The GitBook-GitHub Doc Sync provides bi-directional synchronization, detecting drift in either direction and surfacing conflicts for review. The API Doc Freshness Monitor flags documentation that has gone stale beyond a configurable threshold — an early warning system before consumers are affected.
naftiko: "0.5"
info:
label: "API Doc Freshness Monitor"
description: "Monitors last-modified dates of API specs on GitHub and docs on GitBook, flagging stale entries."
capability:
exposes:
- type: "mcp"
namespace: "freshness-monitor"
tools:
- name: "check-freshness"
description: "Compares spec and doc modification dates and reports staleness."
inputParameters:
- name: owner
in: query
type: string
- name: repo
in: query
type: string
- name: spaceId
in: query
type: string
- name: stale_days
in: query
type: integer
steps:
- name: get-commits
type: call
call: "github.list-commits"
with:
owner: "{{owner}}"
repo: "{{repo}}"
per_page: 1
- name: get-space
type: call
call: "gitbook.get-space"
with:
spaceId: "{{spaceId}}"
- name: "list-stale-spaces"
description: "Lists all spaces and flags those not updated within the staleness threshold."
inputParameters:
- name: gitbook_orgId
in: query
type: string
- name: stale_days
in: query
type: integer
steps:
- name: list-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: "repo-commits"
label: "Repository Commits"
path: "/repos/{{owner}}/{{repo}}/commits"
inputParameters:
- name: "owner"
in: "path"
- name: "repo"
in: "path"
operations:
- name: "list-commits"
method: "GET"
label: "List Commits"
- namespace: "gitbook"
type: "http"
baseUri: "https://api.gitbook.com/v1"
authentication:
type: "bearer"
token: "{{gitbook_token}}"
inputParameters:
- name: "gitbook_token"
in: "environment"
resources:
- name: "space"
label: "Space"
path: "/spaces/{{spaceId}}"
inputParameters:
- name: "spaceId"
in: "path"
operations:
- name: "get-space"
method: "GET"
label: "Get Space"
- name: "org-spaces"
label: "Organization Spaces"
path: "/orgs/{{orgId}}/spaces"
inputParameters:
- name: "orgId"
in: "path"
operations:
- name: "list-spaces"
method: "GET"
label: "List Spaces"
The GitBook Change Request Reviewer brings pull-request-style review discipline to documentation, creating and managing change requests so every doc update is reviewed before publication. The GitBook Collection Organizer structures documentation into domain-based collections so consumers can browse by team, product line, or business domain rather than scrolling through a flat list.
The API Style Guide Enforcer validates documentation against organizational guidelines — checking terminology, page structure, and description quality — and creates change requests for non-conforming pages. The GitBook Search Indexer enables cross-space API discovery, searching across all documentation at once and detecting duplicate or overlapping documentation.
Why Capabilities
The individual workflows here are not complicated. Search GitHub for specs. Create a GitBook space. Upload an OpenAPI file. Compare dates. The complexity is in doing them consistently, across an entire organization, over time. That is what capabilities are designed for.
Each capability is a self-contained YAML file that declares what APIs it consumes, what tools it exposes, and how the steps connect. There is no code to write, no SDK to integrate, no platform to subscribe to. You point the Naftiko Fleet at the YAML and it serves live MCP tools, agent skills, and REST endpoints.
The API visibility problem is not going to be solved by a one-time audit or a documentation sprint. It is going to be solved by making the discovery-to-documentation workflow a repeatable, governed practice — and you can run any of these sixteen capabilities yourself using the open-source Naftiko Fleet.
