bear/api-doc

1.6.0 2026-01-09 08:53 UTC

Requires

• php: ^8.2
• ext-dom: *
• ext-filter: *
• ext-json: *
• ext-libxml: *
• ext-simplexml: *
• bear/app-meta: ^1.7
• bear/package: ^1.9
• bear/resource: ^1.16.2
• bear/sunday: ^1.4
• koriym/app-state-diagram: ^0.11
• koriym/psr4list: ^1.0.1
• michelf/php-markdown: ^1.9.1 || ^2.0
• phpdocumentor/reflection-docblock: ^4.3 || ^5.2
• ray/aop: ^2.10
• ray/di: ^2.16
• rize/uri-template: ^0.3.3 || ^0.4

Requires (Dev)

• bamarni/composer-bin-plugin: ^1.8.2
• bear/aura-router-module: ^2.0.3
• justinrainbow/json-schema: ^5.3 || ^6.0
• koriym/attributes: ^1.0.5
• phpunit/phpunit: ^11.0

MIT

• Akihito Koriyama

README

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

Semantic Depth

The same document reveals different insights depending on your perspective:

Depth	What You See
Surface	Remote function list (API reference)
Middle	Resources and operations (REST design)
Deep	Application semantics (ALPS three layers)

A developer sees endpoints to call. An architect sees state transitions. An AI extracts Ontology, Taxonomy, and Choreography. One document, multiple layers of understanding.

This is a semantic application document, not just an API reference. It describes what the application is, not just how to call it.

Demo

• ApiDoc
• OpenAPI

Installation

composer require bear/api-doc ^1.0

Quick Start

Generate configuration file:

./vendor/bin/apidoc init

This creates apidoc.xml from your composer.json.

Generate documentation:

./vendor/bin/apidoc

Usage

See the API doc documentation.

GitHub Actions

You can use the reusable workflow to generate and publish API documentation automatically.

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

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

Inputs

Input	Default	Description
php-version	'8.2'	PHP version
format	'html,openapi'	Comma-separated: html (apidoc), md, openapi, alps
alps-profile	''	ALPS profile path (required for alps format)
docs-path	'docs/api'	Output directory
publish-to	'github-pages'	github-pages or artifact-only

Output Structure

docs/
├── index.html          # apidoc
├── schemas/            # JSON Schema
│   └── *.json
├── openapi/
│   ├── openapi.json    # OpenAPI spec
│   └── index.html      # Redocly HTML
└── alps/
    ├── alps.json       # ALPS profile
    └── index.html      # ASD HTML

Development

git clone https://github.com/bearsunday/BEAR.ApiDoc.git
cd BEAR.ApiDoc
composer install
composer docs        # Generate docs with external CSS
composer docs-dev    # Generate docs with inline CSS for development
composer docs-md     # Generate Markdown docs
composer docs-openapi # Generate OpenAPI spec

Application as Documentation.