README

Route2API is an open-source API documentation generator for PHP projects. The first version focuses on ThinkPHP: it scans routes and controller comments, then exports OpenAPI, Postman Collection, Markdown, and HTML documents.

中文：Route2API 是一个面向 PHP 项目的接口文档自动生成工具。第一版重点支持 ThinkPHP，可以扫描路由和控制器注释，生成 OpenAPI、Postman Collection、Markdown、HTML 文档，方便导入 Apifox、ApiPost、Postman、Swagger UI、Redoc 等工具。

Features

Scan ThinkPHP route/*.php
Detect Route::get/post/put/delete/patch/any
Detect simple Route::group
Expand Route::resource
Read controller method PHPDoc
Infer request parameters from common controller code patterns
Infer required fields from simple validation rules and requireFields(...)
Export OpenAPI 3.0 JSON
Export OpenAPI 3.0 YAML
Export Postman Collection v2.1 JSON
Export Markdown
Export static HTML
Generate a starter route2api.yaml

Install

Requirements:

PHP 7.0 or later for Route2API itself
ThinkPHP 6.x projects are supported for scanning
ThinkPHP 6 runtime usually requires PHP 7.2.5 or later

Install Route2API as a development dependency in your ThinkPHP project:

composer require route2api/route2api --dev

Quick Start

Run inside a ThinkPHP project:

vendor/bin/route2api scan --framework=thinkphp

Generate all supported formats:

vendor/bin/route2api scan \
  --framework=thinkphp \
  --output=docs/api \
  --format=openapi,yaml,postman,markdown,html

Generated files:

docs/api/openapi.json
docs/api/openapi.yaml
docs/api/postman_collection.json
docs/api/api.md
docs/api/index.html

Configuration

Create a starter config:

vendor/bin/route2api init

This creates route2api.yaml:

project:
  name: Demo API
  base_url: http://localhost

framework: thinkphp

scan:
  routes:
    - route/*.php
  controllers:
    - app/controller

output:
  dir: route2api
  formats:
    - openapi
    - yaml
    - postman
    - markdown
    - html

Then run:

vendor/bin/route2api scan

CLI options can override config values:

vendor/bin/route2api scan \
  --name="My API" \
  --base-url="https://api.example.com" \
  --output=docs/api

Supported ThinkPHP Route Syntax

use think\facade\Route;

Route::get('user/:id', 'User/read');
Route::post('user/login', 'User/login')->middleware('auth');

Route::group('api', function () {
    Route::get('profile', 'Profile/read');
});

Route::resource('articles', 'Article');

Controller Comments

Route2API reads the PHPDoc above controller methods:

/**
 * 用户登录
 * 使用账号密码登录。
 *
 * @param string username 用户名
 * @param string password 密码
 */
public function login()
{
    // ...
}

@param is converted into request parameters in OpenAPI, Markdown, HTML, and Postman output.

Import Into API Tools

Apifox, ApiPost, Postman, Swagger UI, and Redoc can consume the generated output.

Apifox: import openapi.json, openapi.yaml, or postman_collection.json
ApiPost: import openapi.json, openapi.yaml, or postman_collection.json
Postman: import postman_collection.json or openapi.json
Swagger UI / Redoc: use openapi.json or openapi.yaml

Current Limitations

Route2API v0.1 is intentionally small. It uses static analysis and does not execute project code.

Complex nested route groups are not fully parsed yet
Request body schemas are inferred from common patterns such as $this->input(), $this->request->get(...), requireFields(...), and simple validation arrays
Complex dynamic parameters may still need manual cleanup after generation
Full validator and model field scanning are planned
Laravel support is planned
Manual endpoint overrides are planned

The recommended workflow is: scan code first, then use the generated OpenAPI or Markdown as the draft API document.

Roadmap

ThinkPHP validator rule extraction
Request body schema generation
Manual endpoint override file
Laravel route and FormRequest scanner
HTML theme improvements
CI command for regenerating docs
Optional web UI

Contributing

Clone the repository and run the smoke test:

tests/smoke.sh

Run syntax checks:

find . -name '*.php' -exec php -l {} \;

License

MIT

route2api / route2api

Maintainers

Package info

Statistics

Security