API Doc

Your application is the documentation.

• ApiDoc HTML: Developer documentation
• OpenAPI 3.1: Tool chain integration
• JSON Schema: Information model
• ALPS: Vocabulary semantics for AI understanding
• llms.txt: AI-readable application overview

Demo

• HTML
• OpenAPI

Installation

composer require bear/api-doc --dev
./vendor/bin/apidoc init

The init command generates apidoc.xml from your composer.json. Edit it to customize.

<apidoc>
    <appName>MyVendor\MyProject</appName>  <!-- Application namespace -->
    <scheme>app</scheme>                    <!-- app or page -->
    <docDir>docs/api</docDir>
    <format>html</format>                   <!-- html, openapi, etc. -->
</apidoc>

The format accepts comma-separated values: html, md, openapi, llms.

Usage

Generate documentation from the command line.

./vendor/bin/apidoc

OpenAPI HTML Generation

When openapi format is specified, openapi.json is generated. Use Redocly CLI to convert it to HTML.

npm install -g @redocly/cli
redocly build-docs docs/api/openapi.json -o docs/api/openapi.html

llms.txt

The llms format generates llms.txt following the llms.txt specification. The output includes API endpoints, resource objects, infrastructure interfaces (Query/Command), SQL statements, and entity definitions.

Composer Scripts

Add scripts to composer.json for convenience.

{
    "scripts": {
        "docs": "./vendor/bin/apidoc"
    },
    "scripts-descriptions": {
        "docs": "Generate API documentation"
    }
}

composer docs

GitHub Actions

Push to main branch to automatically generate and publish API documentation to GitHub Pages. The reusable workflow handles HTML generation, OpenAPI conversion with Redocly, and ALPS state diagram creation.

name: API Docs
on:
  push:
    branches: [main]

jobs:
  docs:
    uses: bearsunday/BEAR.ApiDoc/.github/workflows/apidoc.yml@v1
    with:
      format: 'html,openapi,llms'

Enable GitHub Pages: Settings → Pages → Source: “GitHub Actions”

Inputs

Output Structure

docs/
├── index.html          # API documentation
├── llms.txt            # AI-readable overview
├── openapi.json        # OpenAPI spec
└── schemas/
    ├── index.html      # Schema list
    └── *.json          # JSON Schema

Configuration

<?xml version="1.0" encoding="UTF-8"?>
<apidoc
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://bearsunday.github.io/BEAR.ApiDoc/apidoc.xsd">
    <appName>MyVendor\MyProject</appName>
    <scheme>app</scheme>
    <docDir>docs</docDir>
    <format>html</format>
    <alps>alps.json</alps>
</apidoc>

Profile

ALPS profile defines your API vocabulary. Centralized definitions prevent inconsistencies and aid shared understanding.

{
    "$schema": "https://alps-io.github.io/schemas/alps.json",
    "alps": {
        "descriptor": [
            {"id": "firstName", "title": "The person's first name."},
            {"id": "familyName", "def": "https://schema.org/familyName"}
        ]
    }
}

Application as Documentation

Code is the single source of truth. Documentation generated from your application never diverges from the implementation.

llms.txt provides AI-readable application overviews. When an AI agent encounters your application, it can quickly grasp the entire structure through this single document—generated directly from your code. Unlike typical API references that list endpoints, llms.txt captures the full information architecture following Dan Klyn’s framework—Ontology, Taxonomy, and Choreography. Combined with ALPS vocabulary semantics and JSON Schema information models, AI agents can understand not just what operations exist, but the meaning and structure behind them.

Reference

• BEAR.ApiDoc - API documentation generator
• ALPS - Application-Level Profile Semantics
• JSON Schema - Data validation and documentation
• Redocly CLI - OpenAPI to HTML conversion