README

Laravel的API蓝图渲染器

这个Laravel包Blueprint Docs可以渲染您的API蓝图。它附带一个标准主题，您可以通过Blade模板进行自定义。安装该包，然后在路由/api-documentation下找到渲染后的文档。

示例输出：如果与API Blueprint样板一起使用，这将生成Blueprint Docs的输出。

API Blueprint是一种基于Markdown的文档格式，它允许您以简单直接的方式编写API描述和文档。目前支持的是API蓝图格式1A。

要求

• Laravel 5.4或更高版本
• Drafter（官方C++ API蓝图解析器）命令行工具
• 在您的Laravel项目根目录中有一个有效的API蓝图blueprint.apib文件（示例文件可用）

Drafter不包含在内，必须事先安装。使用Drafter安装程序composer包来“轻松安装drafter到您的php项目”中。前往那里现在安装它。

安装

通过composer安装包

composer require m165437/laravel-blueprint-docs

接下来，注册其服务提供程序（Laravel >= 5.5自动通过包发现完成此操作）

// config/app.php
'providers' => [
    ...
    M165437\BlueprintDocs\BlueprintDocsServiceProvider::class,
];

可选地，将示例API Blueprint样板文件blueprint.apib发布到您的Laravel项目根目录

php artisan vendor:publish --provider="M165437\BlueprintDocs\BlueprintDocsServiceProvider" --tag="example"

最后，将资产发布到public/vendor/blueprintdocs

php artisan vendor:publish --provider="M165437\BlueprintDocs\BlueprintDocsServiceProvider" --tag="public"

在路由/api-documentation下找到您的文档。

更新

当您更新此包时，您可能需要重新发布其资产（注意添加了参数--force）

php artisan vendor:publish --provider="M165437\BlueprintDocs\BlueprintDocsServiceProvider" --tag="public" --force

配置

要调整Blueprint Docs的配置，将配置文件发布到config/blueprintdocs.php

php artisan vendor:publish --provider="M165437\BlueprintDocs\BlueprintDocsServiceProvider" --tag="config"

配置文件的默认内容如下所示

return [

    /*
    |--------------------------------------------------------------------------
    | Blueprint Docs
    |--------------------------------------------------------------------------
    |
    | Find your rendered docs at the given route or set route to false if you
    | want to use your own route and controller. Provide a fully qualified
    | path to your API blueprint as well as to the required Drafter CLI.
    |
    */

    'route' => 'api-documentation',

    'condense_navigation' => false,

    'blueprint_file' => base_path('blueprint.apib'),

    'drafter' => base_path('vendor/bin/drafter')

];

如果您想使用Blueprint Docs与自己的路由和控制器一起使用，请设置'route' => false，并查看vendor/m165437/laravel-blueprint-docs/src/BlueprintDocsController.php以了解如何设置它。

主题定制

要自定义默认主题，将视图发布到views/vendor/blueprintdocs

php artisan vendor:publish --provider="M165437\BlueprintDocs\BlueprintDocsServiceProvider" --tag="views"

贡献

感谢您考虑为此包做出贡献！有关详细信息，请参阅CONTRIBUTING。

致谢

本软件包高度依赖Hendrik Maus（Hendrik Maus）的工作，尤其是他的Drafter PHP Wrapper和Reynaldo，并受到Aglio的启发，后者是用Node.js编写的API Blueprint渲染器，并提供API Blueprint模板作为示例。标题部分是基于Iconicbestiary创作的图形的修改版，通过Freepik.com提供。

许可协议

Blueprint Docs遵循MIT许可协议（MIT）。有关更多信息，请参阅LICENSE文件。