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.apibin 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.
19 Jul 5, 2021
138 Dec 7, 2022
28 Nov 28, 2022
1.2k Jan 5, 2023
194 Dec 1, 2022
27 Dec 8, 2022
18 Dec 4, 2022
996 Dec 28, 2022
254 Dec 25, 2022
12 Nov 1, 2022
939 Jan 8, 2023
3 Feb 15, 2022
2 Dec 14, 2021
1 Nov 26, 2022
92 May 27, 2022
5 Jul 18, 2022
17 Aug 25, 2022
12 Jan 17, 2022