Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@shalvah
shalvah committed Apr 28, 2019
1 parent 2b12c33 commit 2a43e4a
Show file tree
Hide file tree
Showing 8 changed files with 272 additions and 476 deletions.
400 changes: 7 additions & 393 deletions README.md
View file

Large diffs are not rendered by default.

7 changes: 5 additions & 2 deletions TODO.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
- Add tests for bindings and bindings prefixes
- Add tests for config overrdes
- Add tests for config overrides
- Add tests for faker seed
- Add tests on output
- Add tests on output (deterministic)
- Remove ungrouped_name for default_group
- Bring `bindings` outside of `response_calls`
- Should `routes.*.apply.response_calls.headers` be replaced by `routes.*.apply.headers`?
9 changes: 7 additions & 2 deletions config/apidoc.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,10 +116,15 @@
/*
* For URLs which have parameters (/users/{user}, /orders/{id?}),
* specify what values the parameters should be replaced with.
* Note that you must specify the full parameter, including curly brackets and question marks if any.
* Note that you must specify the full parameter,
* including curly brackets and question marks if any.
*
* You may also specify the preceding path, to allow for variations,
* for instance 'users/{id}' => 1 and 'apps/{id}' => 'htTviP'.
* However, there must only be one parameter per path.
*/
'bindings' => [
// '{user}' => 1
// '{user}' => 1,
],

/*
Expand Down
251 changes: 188 additions & 63 deletions docs/config.md
View file
Original file line number Diff line number Diff line change
@@ -1,89 +1,214 @@
# Configuration

Before you can generate your documentation, you'll need to configure a few things in your `config/apidoc.php`.
Before you can generate your documentation, you'll need to configure a few things in your `config/apidoc.php`. If you aren't sure what an option does, it's best to leave it set to the default. If you don't have this config file, see the [installation instructions](index.md#installation).

- `output`
This is the file path where the generated documentation will be written to. Default: **public/docs**
## `output`
This is the file path where the generated documentation will be written to. Note that the documentation is generated as static HTML and CSS assets, so the route is accessed directly, and not via the Laravel routing mechanism. This path should be relative to the root of your application. Default: **public/docs**

- `postman`
## `router`
The router to use when processing your routes (can be Laravel or Dingo. Defaults to **Laravel**)

## `postman`
This package can automatically generate a Postman collection for your routes, along with the documentation. This section is where you can configure (or disable) that.

- `router`
The router to use when processing the route (can be Laravel or Dingo. Defaults to **Laravel**)
### `enabled`
Whether or not to generate a Postman API collection. Default: **true**

### `name`
The name for the exported Postman collection. If you leave this as null, this package will default to `config('app.name')." API"`.

### `description`
The description for the generated Postman collection.

## `logo`
You can specify a custom logo to be used on the generated documentation. Set the `logo` option to an absolute path pointing to your logo file. For example:
```
'logo' => resource_path('views') . '/api/logo.png'
```

If you want to use this, please note that the image size must be 230 x 52.

## `default_group`
When [documenting your api](documenting.md), you use `@group` annotations to group API endpoints. Endpoints which do not have a ggroup annotation will be grouped under the `default_group`. Defaults to **"general"**.

## `faker_seed`
When generating example requests, this package uses fzanninoto/faker to generate random values. If you would like the package to generate the same example values for parameters on each run, set this to any number (eg. 1234). (Note: alternatively, you can set example values for parameters when [documenting them.](documenting.md#specifying-request-parameters))

## `fractal`
This section only applies if you're using [Transformers]() for your API, and documenting responses with `@transformer` and `@transformerCollection`. Here, you configure how responses are transformed.

> Note: using transformers requires league/fractal package. Run `composer require league/fractal to install
### serializer
If you are using a custom serializer with league/fractal, you can specify it here. league/fractal comes with the following serializers:
- \League\Fractal\Serializer\ArraySerializer::class
- \League\Fractal\Serializer\DataArraySerializer::class
- \League\Fractal\Serializer\JsonApiSerializer::class

- `logo`
You can specify your custom logo to be used on the generated documentation. Set the `logo` option to an absolute path pointing to your logo file.
Leave this as null to use no serializer or return a simple JSON.

- `routes`
This is where you specify what rules documentation should be generated for. You specify routes to be parsed by defining conditions that the routes should meet and rules that should be applied when generating documentation. These conditions and rules are specified in groups, allowing you to apply different rules to different routes.
## `routes`
The `routes` section is an array of items, describing what routes in your application that should have documentation generated for them. Each item in the array contains rules about what routes belong in that group, and what rules to apply to them. This allows you to apply different settings to different routes.

For instance, suppose your configuration looks like this:
> Note: This package does not work with Closure-based routes. If you want your route to be captured by this package, you need a controller.
Each item in the `routes` array (a route group) has keys which are explained below. We'll use this sample route definition for a Laravel app to demonstarte them:

```php
<?php

Route::group(['domain' => 'api.acme.co'], function () {
Route::get('/apps', 'AppController@listApps')
->name('apps.list');
Route::get('/apps/{id}', 'AppController@getApp')
->name('apps.get');
Route::post('/apps', 'AppController@createApp')
->name('apps.create');
Route::get('/users', 'UserController@listUsers')
->name('users.list');
Route::get('/users/{id}', 'UserController@getUser')
->name('users.get');
});

Route::group(['domain' => 'public-api.acme.co'], function () {
Route::get('/stats', 'PublicController@getStats')
->name('public.stats');
});

Route::group(['domain' => 'status.acme.co'], function () {
Route::get('/status', 'PublicController@getStatus')
->name('status');
});
```

### `match`
In this section, you define the rules that will be used to determine what routes in your application fall into this group. There are three kinds of rules defined here (keys in the `match` array):

#### `domains`
This key takes an array of domain names as its value. Only routes which are defined on the domains specified here will be matched as part of this group. For instance, in our sample routes above, we may wish to apply different settings to documentation based on the domains. For instance, the routes on the `api.acme.co` domain need authentication, while those on the other domains do not. We can searate them into two groups like this:

```php
<?php
return [
//...,
//...,

'routes' => [
[
'match' => [
'domains' => ['*'],
'prefixes' => ['api/*', 'v2-api/*'],
'versions' => ['v1'],
],
'include' => ['users.index', 'healthcheck*'],
'exclude' => ['users.create', 'admin.*'],
'apply' => [
'headers' => [
'Authorization' => 'Bearer: {token}',
],
],
],
'routes' => [
[
'match' => [
'domains' => ['api.acme.co'],
'prefixes' => ['*'],
],
'apply' => [
'headers' => [ 'Authorization' => 'Bearer {your-token}']
]
],
[
'match' => [
'domains' => ['public-api.acme.co', 'status.acme.co'],
'prefixes' => ['*'],
],
],
],
];
```
The first group will match all routes on the 'api.acme.co' domain, and add a header 'Authorization: Bearer {your-token}' to the examples in the generated documentation. The second group will pick up the other routes. The Authorization header will not be added for those ones.

This means documentation will be generated for routes in all domains ('&ast;' is a wildcard meaning 'any character') which match any of the patterns 'api/&ast;' or 'v2-api/&ast;', excluding the 'users.create' route and any routes whose names begin with `admin.`, and including the 'users.index' route and any routes whose names begin with `healthcheck.`. (The `versions` key is ignored unless you are using Dingo router).
Also, in the generated documentation, these routes will have the header 'Authorization: Bearer: {token}' added to the example requests.
You can use the `*` wildcard to match all domains (or as a placeholder in a pattern).

You can also separate routes into groups to apply different rules to them:
#### `prefixes`
The prefixes key is similar to the `domains` key, but is based on URL path prefixes (ie. what the part starts with, after the domain name). You could use prefixes to rewrite our example configuration above in a different way:

```php
<?php
return [
//...,
//...,

'routes' => [
[
'match' => [
'domains' => ['v1.*'],
'prefixes' => ['*'],
],
'include' => [],
'exclude' => [],
'apply' => [
'headers' => [
'Token' => '{token}',
'Version' => 'v1',
],
],
],
[
'match' => [
'domains' => ['v2.*'],
'prefixes' => ['*'],
],
'include' => [],
'exclude' => [],
'apply' => [
'headers' => [
'Authorization' => 'Bearer: {token}',
'Api-Version' => 'v2',
],
],
],
'routes' => [
[
'match' => [
'domains' => ['*'],
'prefixes' => ['users/*', 'apps/*'],
],
'apply' => [
'headers' => [ 'Authorization' => 'Bearer {your-token}']
]
],
[
'match' => [
'domains' => ['*'],
'prefixes' => ['stats/*', 'status/*'],
],
],
],
];
```

With the configuration above, routes on the `v1.*` domain will have the `Token` and `Version` headers applied, while routes on the `v2.*` domain will have the `Authorization` and `Api-Version` headers applied.
This would achieve the same as the first configuration. As with domains, the `*` character is a wildcard. This means you can set up a ingle group to match all your routes by using `'domains' => ['*'], 'prefixes' => ['*']`. (This is set by default.)

> The `domains` and `prefixes` keys are both required for all route groups.
#### `versions`
> This section only applies if you're using Dingo Router
When using Dingo's Router, all routes must be specified inside versions. This means that you must specify the versions to be matched along with the domains and prefixes when describing a route group. Note that wildcards in `versions` are not supported; you must list out all your versions explicitly. Example:

```php
<?php
return [
//...,

'routes' => [
[
'match' => [
'domains' => ['*'],
'prefixes' => ['*'],
'versions' => ['v1', 'beta'], // only if you're using Dingo router
],
],
],
];
```

### `include` and `exclude`
The `include` key holds an array of route names which should be included in this group, *even if they do not match the rules in the `match` section*.
The `exclude` key holds an array of route names which should be excluded from this group, *even if they match the rules in the `match` section*.

> Remember that these two keys work with route *names*, not paths.
Using our above sample routes, asuming you wanted to place the `users.list` route in the second group (no Authorization header), here's how you could do it:

```php
<?php
return [
//...,

'routes' => [
[
'match' => [
'domains' => ['api.acme.co'],
'prefixes' => ['*'],
],
'exclude' => ['users.list'],
'apply' => [
'headers' => [ 'Authorization' => 'Bearer {your-token}']
]
],
[
'match' => [
'domains' => ['public-api.acme.co', 'status.acme.co'],
'prefixes' => ['*'],
],
'include' => ['users.list'],
],
],
];
```

### `apply`
After defining the routes in `match` (and `include` or `exclude`), `apply` is where you specify the settings to be applied to those routes when generating documentation. There are a bunch of settings you can tweak here:

#### `headers`
Like we've demonstrated above, any headers you specify here will be added to the headers shown in the example requests in your documenation. Headers are specified as key => value strings.

> Note: the `include` and `exclude` items are arrays of route names. THe &ast; wildcard is supported.
> Note: If you're using DIngo router, the `versions` parameter is required in each route group. This parameter does not support wildcards. Each version must be listed explicitly,
#### `response_calls`
These are the settings that will be applied when making ["response calls"](documenting.md#generating-responses-automatically). See the linked section for details.
9 changes: 9 additions & 0 deletions docs/description.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# How This Works

After installing this package and runing the command `php artisan apidoc:generate` in your application, here's what happens:

- The package fetches all your application's routes.
- It looks through your [configuration file](config.md) to filter the routes to the ones you actually want to document. For each route, it retrieves the settings you want to apply to it, if any.
- It processes each route. "Process" here involves using a number of strategies to extract the route's information: group, title, description, body parameters, query parameters, and a sample response, if possible.
- After processing the routes, it generates a markdown file describing the routes from the parsed data and passes them to [Documentarian](https://github.com/mpociot/documentarian), which wraps them in a theme and converts them into HTML and CSS.
- It generates a Postman API collection for your routes. ([This can be disabled.](config.md#postman))
Loading

0 comments on commit 2a43e4a

Please sign in to comment.