README

API Blueprint Renderer for Laravel

This Laravel package Blueprint Docs renders your API Blueprint. It comes with a standard theme that you can customize via Blade templates. Install the package and find your rendered documentation at route /api-documentation.

Example output: If used with API Blueprint boilerplate, this would be Blueprint Docs' output.

API Blueprint is a Markdown-based document format that lets you write API descriptions and documentation in a simple and straightforward way. Currently supported is API Blueprint format 1A.

Requirements

Laravel 5.4 or greater
Drafter (the official C++ API Blueprint parser) command line tool
A valid API Blueprint blueprint.apib in the root directory of your Laravel project (example available)

Drafter is not included and must be installed beforehand. Use the Drafter Installer composer package to "install drafter in your php project with ease". Head over there and install it now.

Installation

Install the package via composer:

composer require m165437/laravel-blueprint-docs

Next, register its service provider (Laravel >= 5.5 does this automatically via Package Discovery):

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

Optionally, publish the example API Blueprint boilerplate file blueprint.apib to the root directory of your Laravel project:

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

Finally, publish its assets to public/vendor/blueprintdocs:

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

Find your documentation at route /api-documentation.

Update

When you update this package, you might need to republish its assets (note the added parameter --force):

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

Configuration

To adjust Blueprint Docs' configuration, publish its config file to config/blueprintdocs.php:

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

The default contents of the configuration file look like this:

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')

];

If you want to use Blueprint Docs with your own route and controller, set 'route' => false and have a look at vendor/m165437/laravel-blueprint-docs/src/BlueprintDocsController.php to get an idea on how to set it up.

Theming

To customize the default theme, publish its views to views/vendor/blueprintdocs:

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

Contributing

Thank you for considering contributing to this package! Please see CONTRIBUTING for details.

Credits

This package relies heavily on work done by Hendrik Maus, namely his Drafter PHP Wrapper and Reynaldo, it's inspired by Aglio, an API Blueprint renderer written in Node.js, and provides the API Blueprint boilerplate as an example. The header is the modified part of a graphic created by Iconicbestiary, via Freepik.com.

License

Blueprint Docs is licensed under the MIT License (MIT). Please see the LICENSE file for more information.

m165437 / laravel-blueprint-docs

Maintainers

Details