styde / enlighten
Enlighten your APIs with auto-generated documentation
Installs: 2 717
Dependents: 0
Suggesters: 0
Security: 0
Stars: 490
Watchers: 12
Forks: 33
Open Issues: 6
Requires
- php: ^7.3|^8.0
- ext-json: *
- guzzlehttp/guzzle: ^7.2
- laravel/framework: ^7.28|^8.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^2.16
- orchestra/testbench: ^5.0|^6.0
- phpunit/phpunit: ^9.3
- dev-main
- 0.5.7
- 0.5.6
- 0.5.5
- 0.5.4
- 0.5.3
- 0.5.2
- 0.5.1
- 0.5.0
- 0.4.5
- 0.4.4
- 0.4.3
- 0.4.2
- 0.4.1
- 0.4.0
- 0.3.6
- 0.3.5
- 0.3.4
- 0.3.3
- 0.3.2
- 0.3.1
- 0.3.0
- 0.2.9
- 0.2.8
- 0.2.7
- 0.2.6
- 0.2.5
- 0.2.4
- 0.2.3
- 0.2.2
- 0.2.1
- 0.2.0
- 0.1.2
- 0.1.1
- 0.1.0
- dev-dev
- dev-feature/api
- dev-feature/endpoints-views
- dev-feature/code_snippets
- dev-feature/example-slug
- dev-feature/export-documentation
- dev-feature/collision-printer
- dev-feature/view-widgets
- dev-search-box
- dev-github-tests
This package is auto-updated.
Last update: 2021-01-15 21:34:52 UTC
README
A seamless package to document your Laravel APIs.
There is no need to add endless docblocks to each API method, maintain dozens of read me files, or write extensive wikis to keep your APIs documented and in sync with your codebase!
Enlighten your Laravel applications with a beautiful documentation generated automatically from your test suites, by doing so, your documentation will always be updated with the current version of your app.
If you have already invested a lot of time developing and testing your API you don't need to spend the same amount of time documenting it, we'll do that for you, you deserve it!
You can be a part of this project:
Introducing Laravel Enlighten
After installing the component, run phpunit
and that's it! You'll find the entire API documentation in the following URL: /enlighten/
Usage
After finishing the installation process, run your Laravel tests as usual.
phpunit
Now visit /enlighten/
to navigate the documentation.
Run php artisan enlighten:export
to export the documentation as static files!
Demo project
Follow our 3min installation guide to see Enlighten in action in your own app (you don't need to modify your tests!)
Alternatively, install our demo project following the instructions in its README.
Installation
Installing Enlighten requires only 3 steps!
First: require the package with Composer as a dev dependency:
composer require styde/enlighten --dev
If you are not using the Laravel package auto-discovery feature, please add the following service-provider to config/app.php
[ 'providers' => [ // ... Styde\Enlighten\Providers\EnlightenServiceProvider::class, ] ];
Second: Run php artisan enlighten:install
to install and setup Enlighten automatically, otherwise follow the instructions in the Manual Setup Section.
Third: create and configure a database for Enlighten following the instructions below:
Database Setup
Enlighten
needs its own database and database connection to record and preserve the information from your test-suite.
If you use the following convention:
- A non-sqlite default database for your local enviroment (i.e.
my_db
) - A non-sqlite database for your test enviroment with the
_test
or_tests
suffix (i.e.my_db_tests
)
Just add a new database using the same name of your default database with the _enlighten
suffix, for example:
# .env
# If your local database is:
DB_NAME=my_default_database
#
# phpunit.xml
# And your test database is:
# <env name="DB_DATABASE" value="my_default_database_tests"/>
#
# Then Enlighten will use a third database automatically:
# my_default_database_enlighten
If you're not following the convention above, just add a new connection entry in config/database.php
with the name enlighten
and your custom configuration:
'enlighten' => [
'driver' => 'mysql',
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '3306'),
'database' => 'my_enlighten_database',
// ...
],
After creating the new database, run the migrations using Artisan:
php artisan migrate
It's important to have a different connection and a different database for Enlighten in order to avoid having the info deleted or not persisted when using any of the database migration traits included by Laravel or if you run the tests using SQLite.
You can use the enlighten:migrate
artisan commands to run the package migrations in isolation, before doing this, you'll need to publish the database migration files:
php artisan vendor:publish --tag=enlighten-migrations
Now you can use:
php artisan enlighten:migrate php artisan enlighten:migrate:fresh
Manual Setup
If you didn't run php artisan enlighten:install
or you received an error message, you can setup Enlighten manually following these instructions:
Publish the package assets (CSS, JavaScript) to the public folder using Artisan:
php artisan vendor:publish --tag=enlighten-build
Optionally, you can publish the config file and views for more customization.
php artisan vendor:publish --tag=enlighten-config php artisan vendor:publish --tag=enlighten-views
Third step: import the trait Styde\Enlighten\Tests\EnlightenSetup
and call $this->setUpEnlighten()
in the setUp
method of your TestCase
, for example:
<?php namespace Tests; use Styde\Enlighten\Tests\EnlightenSetup; class TestCase extends \Tests\TestCase { use EnlightenSetup; protected function setUp(): void { parent::setUp(); $this->setUpEnlighten(); } }
Note: remember to include and use the trait Styde\Enlighten\Tests\EnlightenSetup
.
"See in Enlighten" link
Add the printerClass
attribute with the value Styde\Enlighten\Tests\BasicResultPrinter
to the phpunit
tag in phpunit.xml
like in the example below. Don't delete the other attributes!
<phpunit [...] printerClass="Styde\Enlighten\Tests\BasicResultPrinter">
Optional configuration
To "group" your tests-classes as "modules", you can use a regular expression to find all the classes that match with the given pattern or patterns:
// config/enlighten.php [ 'modules' => [ [ 'name' => 'Users', 'pattern' => ['*Users*'] ], [ 'name' => 'Projects', 'pattern' => ['*Projects*', '*Project*'] ], [ 'name' => 'Other Modules', 'pattern' => ['*'], ], ] ];
You can add a "catch all" group at the end to include all those files that didn't match with any of the other patterns, otherwise Enlighten will do this automatically for you.
Excluding test-classes from the documentation
If you want to include all the test-classes and methods in your documentation, you can skip this step, otherwise, you can add the following key to the /config/enlighten.php
file:
[ 'tests' => [ // Add expressions to ignore test class names and test method names. // i.e. Tests\Unit\* ignores all tests in the Tests\Unit\ suite, // validates_* ignores all tests that start with validates_. 'ignore' => [ 'method_that_will_be_ignored', ], ], ];
You can also ignore classes and methods adding the @enlighten {"ignore": true}
annotation to any class OR method, for example:
/** * @enlighten {"ignore": true} */ class IgnoreClassWithAnnotationTest extends TestCase { use RefreshDatabase; /** * @test * @enlighten {"ignore": true} */ function does_not_export_test_methods_with_the_enlighten_ignore_annotation() { $this->assertExampleIsNotCreated(); } }
If you'd like to do the opposite (include a class previously ignored via the configuration option) just add the @enlighten annotation to that class OR method:
/** * @enlighten */ class IncludeMethodWithAnnotationTest extends TestCase { /** * @test * @enlighten */ function export_test_method_with_the_enlighten_annotation_even_if_its_ignored_in_the_config() { $this->assertExampleIsCreated(); } }
Note: the annotations take precedence over the configuration option.
Customizing titles and descriptions
If you want to have more control on the titles of the classes and methods, or add descriptions to each group or example, you can add the following annotations in your test classes and methods:
/** * @title User Module * * or if you prefer: * * @testdox User Module * * and you can also use: * * @description Manage all the user-related petitions. **/ class UsersTest extends TestCase { /** * * @testdox Create Users * * @description Register a new user via POST request. API credentials must be provided. **/ public function testRegisterNewUsers() { $this->assertTrue(true); } }
Hiding sections from the view
You can hide entire UI sections from the view via config
// config/enlighten.php return [ // Add values to this array if you want to hide certain sections from your views. // For valid sections see \Styde\Enlighten\Section 'hide' => [ // ], ];
Document your Internal API (Classes, Methods and Functions)
You can also create a code-snippet from your unit-tests by using the Enlighten::test()
facade, this will allows you to add code-examples to your documentation.
use Styde\Enlighten\Facades\Enlighten; class CalcTest extends TestCase { /** * @test * @testdox Sum two numbers * @description Use the Calc `sum` static method to sum two numbers. **/ public function can_sum_two_numbers() { $result = Enlighten::test(function () { $a = 1; $b = 2; return Calc::sum($a, $b); }); $this->assertSame(3, $result); } }
Optionally, you can use the enlighten()
helper instead of the Enlighten::test()
facade.
Export the documentation as static HTML files
Since v0.4
you can use artisan to generate static files for your documentation:
php artisan enlighten:export
You can select a custom export directory and base URL to use on the static files.
Customizing the intro page
To customize the content of your Dashboard page, you can add an ENLIGHTEN.md
markdown file to the root path of your project.
The content of this file will overwrite the default page provided by this package.
Community Links
English
- Enlighten Your APIs With Auto-Generated Documentation (LaravelNews.com)
- Composer 2.0, Enlightened APIs, and Mastering Nova (LaravelNews Podcast)
- Documentation in Laravel 8 with Enlighten (Oliver Earl)
Spanish
German
Credits
License
The MIT License (MIT). Please see License File for more information.