Wallogit.com
2017 © Pedro Peláez
A tool to generate and display api docs
, (*1)
This package contains the documentation generator & documentation viewer. The packaged reads json from a folder and turns it into a website with api info. It also includes a generator., (*2)
, (*3)
composer require "ilovelaravel/docs":"dev-master", (*4)
Publish config the config, (*5)
php artisan vendor:publish, (*6)
All files needed are stored in storage/docs. The main file is storage/docs/api.json., (*7)
All generated files live in storage/docs/generated. Copy them over to storage/docs after generation., (*8)
You can control where the docs pages are being served from by adding an entry to you .env file., (*9)
I use this when I am working on the docs: DOCS_DIRECTORY=storage/docs/generated
..and when I am happy, I change it to: DOCS_DIRECTORY=storage/docs, (*10)
Run the following command to generate the files:, (*11)
php artisan api:docs:generate, (*12)
There you will find the following structure:, (*13)
# Main file which structure we use to create the views /api.json # Example request + response objects /examples /examples/<collection_name>/responses/named.route.json /examples/<collection_name>/requests/named.route.json # Examples of headers for the requests /headers # All the resources(GET,POST,PUT,DELETE) per collection /resources /resources/<collection_name>.json
Routes should look like this:, (*14)
$this->get('users', 'UsersController@index')->name('api.users.index')->middleware('can:users.read');
The generator only looks at named routes starting with api. Like this: ->name(api.something.something)
The generator can extract permissions from routes that use the can middleware., (*15)
The frontend views are currently showing a menu, which can be build by preparing the routes like this:, (*16)
# group names turn in to menu items. Below 'general', will be the parent.
# collection will be the name of the child menu name.
$this->group(['group'=>'general','collection'=>'users'],
function() {
// ..
});
$this->group(['group'=>'general','collection'=>'dogs'],
function() {
// ..
});
$this->group(['group'=>'addresses','collection'=>'companies'],
function() {
// ..
});
This will result in a menu looking like this:, (*17)
General
- Users
- Dogs
Addresses
- Companies
Annotations should be placed on controller methods.
- @NoAuth For methods that do not need authentication
- @Title("Show all users") A title that describes the api action
- @Info("This will return all users") Some information about the action, (*18)
/**
* @Title("Show all users")
* @Info("This will return all users")
* @return JsonResponse
*/
public function index(): JsonResponse
{
// ..
}
If you create new form requests, for new api actions, then you could use the artisan command:, (*19)
docs:make:request AddUserRequest, (*20)
If you update existing form request objects, then you should add the Guarded trait and implement the ApiRequestContract contract., (*21)
Both the rules() and the schema method should at least return an empty array;, (*22)
```php, (*23)
// Regular request validation rules. Please always fill this completely,
// also for optional(nullable) fields, (*24)
public function rules() { return [ 'first_name' => 'required|string' ] }, (*25)
// This will show up in the documentation. The format is: // array('parameter key','validation rules','example of expected input'), (*26)
public function schema() { // Faker can be used to generated example output $faker = \Faker\Factory::create();, (*27)
return [
['first_name','required|string', $faker->firstName], // use faker like this
['key','validation','example'], // etc etc
['key','validation','example'] // etc
]
}, (*28)
### Responses The structure of the folder ```examples``` looks like this:: ``` examples/ example/requests/named.route.namespace.json example/responses/named.route.namespace.json ``` The requests and response files have the same name as your named route. All generated files will be stored in the ```docs/generated``` folder. This should be your main folder. Configure this in your config. Copy files from there into the main folder. This way you can preview changes in without losing information that is allready generated before. ### Routes command ```php artisan docs:routes``` will give you a clean preview of the routes that will be used  ### Views The documentation can be viewed in the browser: ```http(s)://your-url.something/docs``` If you like to edit the views, you need to publish them. After publishing the views for the templates can be found at: ```resources/views/docs``` I went fast & wonderfull to create this generator. The least important part for me were the views, so they contain a lovely hackjob of inline javascript an some css, which could be refactored, if you care. For me it has absolutely no priority. ## Changelog Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently. ## Testing You can run this command to see that nothing happens. Maybe some errors. ```bash composer test
The MIT License (MIT). Please see License File for more information., (*29)
A tool to generate and display api docs
MIT
laravel api docs