Merge pull request #326 from bearsunday/apidoc-manual

docs: update apidoc manual for init command

Author: koriym

manuals/1.0/en/apidoc.md

@@ -23,7 +23,56 @@ Your application is the documentation.
 
 ```bash
 composer require bear/api-doc --dev
-cp vendor/bear/api-doc/apidoc.xml.dist apidoc.xml
+./vendor/bin/apidoc init
+```
+
+The `init` command generates `apidoc.xml` from your `composer.json`. Edit it to customize.
+
+```xml
+<apidoc>
+    <appName>MyVendor\MyProject</appName>  <!-- Application namespace -->
+    <scheme>app</scheme>                    <!-- app or page -->
+    <docDir>docs/api</docDir>
+    <format>html</format>                   <!-- html, html,openapi, etc. -->
+</apidoc>
+```
+
+The `format` accepts comma-separated values: `html`, `md`, `openapi`.
+
+## Usage
+
+Generate documentation from the command line.
+
+```bash
+./vendor/bin/apidoc -capidoc.xml
+```
+
+### OpenAPI HTML Generation
+
+When `openapi` format is specified, `openapi.json` is generated. Use Redocly CLI to convert it to HTML.
+
+```bash
+npm install -g @redocly/cli
+redocly build-docs docs/api/openapi/openapi.json -o docs/api/openapi/index.html
+```
+
+### Composer Scripts
+
+Add scripts to `composer.json` for convenience.
+
+```json
+{
+    "scripts": {
+        "docs": "./vendor/bin/apidoc"
+    },
+    "scripts-descriptions": {
+        "docs": "Generate API documentation"
+    }
+}
+```
+
+```bash
+composer docs
 ```
 
 ## GitHub Actions
@@ -98,7 +147,7 @@ docs/
 
 ## Profile
 
-[ALPS](http://alps.io/) profile defines your API vocabulary. Centralized definitions prevent inconsistencies and aid shared understanding.
+ALPS profile defines your API vocabulary. Centralized definitions prevent inconsistencies and aid shared understanding.
 
 ```json
 {
@@ -118,4 +167,7 @@ Code is the single source of truth. Documentation generated from your applicatio
 
 ## Reference
 
-- [ALPS](https://www.app-state-diagram.com/manuals/1.0/en/)
+- [BEAR.ApiDoc](https://github.com/bearsunday/BEAR.ApiDoc) - API documentation generator
+- [ALPS](https://www.app-state-diagram.com/manuals/1.0/en/) - Application-Level Profile Semantics
+- [JSON Schema](https://json-schema.org/) - Data validation and documentation
+- [Redocly CLI](https://redocly.com/docs/cli/installation/) - OpenAPI to HTML conversion

manuals/1.0/ja/apidoc.md

@@ -23,7 +23,56 @@ permalink: /manuals/1.0/ja/apidoc.html
 
 ```bash
 composer require bear/api-doc --dev
-cp vendor/bear/api-doc/apidoc.xml.dist apidoc.xml
+./vendor/bin/apidoc init
+```
+
+`init`コマンドは`composer.json`から`apidoc.xml`を生成します。必要に応じて編集してください。
+
+```xml
+<apidoc>
+    <appName>MyVendor\MyProject</appName>  <!-- アプリケーションの名前空間 -->
+    <scheme>app</scheme>                    <!-- app または page -->
+    <docDir>docs/api</docDir>
+    <format>html</format>                   <!-- html, html,openapi など -->
+</apidoc>
+```
+
+`format`には`html`、`md`、`openapi`をカンマ区切りで指定できます。
+
+## 使い方
+
+コマンドラインからドキュメントを生成します。
+
+```bash
+./vendor/bin/apidoc -capidoc.xml
+```
+
+### OpenAPI HTML生成
+
+`openapi`形式を指定すると`openapi.json`が生成されます。これをHTMLに変換するにはRedocly CLIを使用します。
+
+```bash
+npm install -g @redocly/cli
+redocly build-docs docs/api/openapi/openapi.json -o docs/api/openapi/index.html
+```
+
+### Composerスクリプト
+
+`composer.json`にスクリプトを追加すると便利です。
+
+```json
+{
+    "scripts": {
+        "docs": "./vendor/bin/apidoc"
+    },
+    "scripts-descriptions": {
+        "docs": "Generate API documentation"
+    }
+}
+```
+
+```bash
+composer docs
 ```
 
 ## GitHub Actions
@@ -98,7 +147,7 @@ docs/
 
 ## プロファイル
 
-[ALPS](http://alps.io/)プロファイルはAPIの語彙を定義します。定義を集中させることで表記揺れを防ぎ、理解共有を助けます。
+ALPSプロファイルはAPIの語彙を定義します。定義を集中させることで表記揺れを防ぎ、理解共有を助けます。
 
 ```json
 {
@@ -118,4 +167,7 @@ docs/
 
 ## リファレンス
 
-- [ALPS](https://www.app-state-diagram.com/manuals/1.0/ja/)
+- [BEAR.ApiDoc](https://github.com/bearsunday/BEAR.ApiDoc) - APIドキュメント生成ツール
+- [ALPS](https://www.app-state-diagram.com/manuals/1.0/ja/) - Application-Level Profile Semantics
+- [JSON Schema](https://json-schema.org/) - データ検証とドキュメンテーション
+- [Redocly CLI](https://redocly.com/docs/cli/installation/) - OpenAPIからHTMLへの変換