You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Ability to override the controller `@group` from the method. (https://github.com/mpociot/laravel-apidoc-generator/pull/372)
47
22
48
23
### Changed
49
-
- Response calls are now only made when route is GET (https://github.com/mpociot/laravel-apidoc-generator/pull/279)
50
-
- Validator factory is now passed to `FormRequest::validator` method (https://github.com/mpociot/laravel-apidoc-generator/pull/236)
51
-
- Bind optional model parameters in routes (https://github.com/mpociot/laravel-apidoc-generator/pull/297/)
52
-
- HEAD routes are no longer automatically generated for GET routes (https://github.com/mpociot/laravel-apidoc-generator/pull/180)
53
-
-`actAsUserId` option is no longer cast to an int (https://github.com/mpociot/laravel-apidoc-generator/pull/257)
24
+
- Moved from command-line options to a config file (https://github.com/mpociot/laravel-apidoc-generator/pull/362)
25
+
- Commands have been renamed to the `apidoc` namespace (previously `api`). (https://github.com/mpociot/laravel-apidoc-generator/pull/350)
26
+
- The `update` command has been renamed to `rebuild` and now uses the output path configured in the config file. (https://github.com/mpociot/laravel-apidoc-generator/pull/370)
27
+
-`@resource` renamed to `@group` (https://github.com/mpociot/laravel-apidoc-generator/pull/371)
54
28
55
29
### Fixed
56
-
-`useMiddleware` option is now actually used (https://github.com/mpociot/laravel-apidoc-generator/pull/297/)
57
-
- Changes to the info vendor view are now persisted (https://github.com/mpociot/laravel-apidoc-generator/pull/120)
Copy file name to clipboardExpand all lines: README.md
+59-26Lines changed: 59 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
## Laravel API Documentation Generator
2
2
3
-
Automatically generate your API documentation from your existing Laravel/[Dingo](https://github.com/dingo/api) routes. [Here's what the output looks like](http://marcelpociot.de/whiteboard/).
3
+
Automatically generate your API documentation from your existing Laravel/Lumen/[Dingo](https://github.com/dingo/api) routes. [Here's what the output looks like](http://marcelpociot.de/whiteboard/).
4
4
5
5
`php artisan apidoc:generate`
6
6
@@ -17,12 +17,7 @@ Automatically generate your API documentation from your existing Laravel/[Dingo]
17
17
> Note: version 3.x requires PHP 7 and Laravel 5.5 or higher.
This means documentation will be generated for routes in all domains ('***' is a wildcard meaning 'any character') which match any of the patterns 'api/*' or 'v2-api/*', excluding the 'users.create' route, and including the 'users.index' route. (The `versions` key is ignored unless you are using Dingo router).
68
+
This means documentation will be generated for routes in all domains ('*' is a wildcard meaning 'any character') which match any of the patterns 'api/*' or 'v2-api/*', excluding the 'users.create' route, and including the 'users.index' route. (The `versions` key is ignored unless you are using Dingo router).
74
69
Also, in the generated documentation, these routes will have the header 'Authorization: Bearer: {token}' added to the example requests.
75
70
76
71
You can also separate routes into groups to apply different rules to them:
@@ -133,43 +128,61 @@ This package uses these resources to generate the API documentation:
133
128
134
129
This package uses the HTTP controller doc blocks to create a table of contents and show descriptions for your API methods.
135
130
136
-
Using `@group` in a doc block prior to each controller is useful as it creates a Group within the API documentation for all methods defined in that controller (rather than listing every method in a single list for all your controllers), but using `@resource` is not required. The short description after the `@resource` should be unique to allow anchor tags to navigate to this section. A longer description can be included below. Custom formatting and `<aside>` tags are also supported. (see the [Documentarian docs](http://marcelpociot.de/documentarian/installation/markdown_syntax))
131
+
Using `@group` in a controller doc block creates a Group within the API documentation. All routes handled by that controller will be grouped under this group in the sidebar. The short description after the `@group` should be unique to allow anchor tags to navigate to this section. A longer description can be included below. Custom formatting and `<aside>` tags are also supported. (see the [Documentarian docs](http://marcelpociot.de/documentarian/installation/markdown_syntax))
132
+
133
+
> Note: using `@group` is optional. Ungrouped routes will be placed in a "general" group.
137
134
138
135
Above each method within the controller you wish to include in your API documentation you should have a doc block. This should include a unique short description as the first entry. An optional second entry can be added with further information. Both descriptions will appear in the API documentation in a different format as shown below.
136
+
You can also specify an `@group` on a single method to override the group defined at the controller level.
139
137
140
138
```php
141
139
/**
142
-
* @resource Example
140
+
* @group User management
143
141
*
144
-
* Longer description
142
+
* APIs for managing users
145
143
*/
146
-
class ExampleController extends Controller {
144
+
class UserController extends Controller
145
+
{
147
146
148
147
/**
149
-
* This is the short description [and should be unique as anchor tags link to this in navigation menu]
148
+
* Create a user
150
149
*
151
-
* This can be an optional longer description of your API call, used within the documentation.
150
+
* [Insert optional longer description of the API endpoint here.]
To specify a list of valid parameters your API route accepts, use the `@bodyParam` annotation. It takes the name of the parameter, its type, an optional "required" label, and then its description
175
+
To specify a list of valid parameters your API route accepts, use the `@bodyParam` and `@queryParam` annotations.
176
+
- The `@bodyParam` annotation takes the name of the parameter, its type, an optional "required" label, and then its description.
177
+
- The `@queryParam` annotation (coming soon!) takes the name of the parameter, an optional "required" label, and then its description
166
178
167
179
168
180
```php
169
181
/**
170
182
* @bodyParam title string required The title of the post.
171
183
* @bodyParam body string required The title of the post.
172
-
* @bodyParam type The type of post to create. Defaults to 'textophonious'.
184
+
* @bodyParam type string The type of post to create. Defaults to 'textophonious'.
185
+
* @bodyParam author_id int the ID of the author
173
186
* @bodyParam thumbnail image This is required if the post type is 'imagelicious'.
174
187
*/
175
188
public function createPost()
@@ -180,11 +193,15 @@ public function createPost()
180
193
181
194
They will be included in the generated documentation text and example requests.
You can provide an example response for a route. This will be disaplyed in the examples section. There are several ways of doing this.
198
+
187
199
200
+
### Indicating auth status
201
+
You can use the `@authenticated` annotation on a method to indicate if the endpoint is authenticated. A "Requires authentication" badge will be added to that route in the generated documentation.
202
+
203
+
### Providing an example response
204
+
You can provide an example response for a route. This will be displayed in the examples section. There are several ways of doing this.
188
205
189
206
#### @response
190
207
You can provide an example response for a route by using the `@response` annotation with valid JSON:
@@ -206,7 +223,7 @@ public function show($id)
206
223
#### @transformer, @transformerCollection, and @transformerModel
207
224
You can define the transformer that is used for the result of the route using the `@transformer` tag (or `@transformerCollection` if the route returns a list). The package will attempt to generate an instance of the model to be transformed using the following steps, stopping at the first successful one:
208
225
209
-
1. Check if there is a `@transformerModel` tag to define the model being transformed. If there is none, use the class of the first parameter to the method.
226
+
1. Check if there is a `@transformerModel` tag to define the model being transformed. If there is none, use the class of the first parameter to the transformer's `transform()`method.
210
227
2. Get an instance of the model from the Eloquent model factory
211
228
2. If the parameter is an Eloquent model, load the first from the database.
212
229
3. Create an instance using `new`.
@@ -244,11 +261,27 @@ public function showUser(int $id)
244
261
```
245
262
For the first route above, this package will generate a set of two users then pass it through the transformer. For the last two, it will generate a single user and then pass it through the transformer.
246
263
247
-
#### Postman collections
264
+
> Note: for transformer support, you need to install the league/fractal package
265
+
266
+
```bash
267
+
composer require league/fractal
268
+
```
269
+
270
+
#### Gnerating responses automatically
271
+
If you don't specify an example response using any of the above means, this package will attempt to get a sample response by making a request to the route (a "response call"). A few things to note about response calls:
272
+
- They are done within a database transaction and changes are rolled back afterwards.
273
+
- The configuration for response calls is located in the `config/apidoc.php`. They are configured within the `['apply']['response_calls']` section for each route group, allowing you to apply different settings for different sets of routes.
274
+
- By default, response calls are only made for GET routes, but you can configure this. Set the `methods` key to an array of methods or '*' to mean all methods. Leave it as an empty array to turn off response calls for that route group.
275
+
- Parameters in URLs (example: `/users/{user}`, `/orders/{id?}`) will be replaced with '1' by default. You can configure this, however.Put the parameter names (including curly braces and question marks) as the keys and their replacements as the values in the `bindings` key.
276
+
- You can configure environment variables (this is useful so you can prevent external services like notifications from being triggered). By default the APP_ENV is set to 'documentation'. You can add more variables in the `env` key.
277
+
- You can also configure what headers, query parameters and body parameters should be sent when making the request (the `headers`, `query`, and `body` keys respectively).
278
+
279
+
280
+
### Postman collections
248
281
249
282
The generator automatically creates a Postman collection file, which you can import to use within your [Postman app](https://www.getpostman.com/apps) for even simpler API testing and usage.
250
283
251
-
If you don't want to create a Postman collection, set the `--postman` config option to false.
284
+
If you don't want to create a Postman collection, set the `postman` config option to false.
252
285
253
286
The default base URL added to the Postman collection will be that found in your Laravel `config/app.php` file. This will likely be `http://localhost`. If you wish to change this setting you can directly update the url or link this config value to your environment file to make it more flexible (as shown below):
254
287
@@ -267,10 +300,10 @@ APP_URL=http://yourapp.app
267
300
If you want to modify the content of your generated documentation, go ahead and edit the generated `index.md` file.
268
301
The default location of this file is: `public/docs/source/index.md`.
269
302
270
-
After editing the markdown file, use the `apidoc:update` command to rebuild your documentation as a static HTML file.
303
+
After editing the markdown file, use the `apidoc:rebuild` command to rebuild your documentation as a static HTML file.
271
304
272
305
```sh
273
-
$ php artisan apidoc:update
306
+
$ php artisan apidoc:rebuild
274
307
```
275
308
276
309
As an optional parameter, you can use `--location` to tell the update command where your documentation can be found.
0 commit comments