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
+56-18Lines changed: 56 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -128,43 +128,61 @@ This package uses these resources to generate the API documentation:
128
128
129
129
This package uses the HTTP controller doc blocks to create a table of contents and show descriptions for your API methods.
130
130
131
-
Using `@resource` 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.
132
134
133
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.
134
137
135
138
```php
136
139
/**
137
-
* @resource Example
140
+
* @group User management
138
141
*
139
-
* Longer description
142
+
* APIs for managing users
140
143
*/
141
-
class ExampleController extends Controller {
144
+
class UserController extends Controller
145
+
{
142
146
143
147
/**
144
-
* This is the short description [and should be unique as anchor tags link to this in navigation menu]
148
+
* Create a user
145
149
*
146
-
* 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
161
178
162
179
163
180
```php
164
181
/**
165
182
* @bodyParam title string required The title of the post.
166
183
* @bodyParam body string required The title of the post.
167
-
* @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
168
186
* @bodyParam thumbnail image This is required if the post type is 'imagelicious'.
169
187
*/
170
188
public function createPost()
@@ -175,11 +193,15 @@ public function createPost()
175
193
176
194
They will be included in the generated documentation text and example requests.
177
195
178
-
**Result:**
196
+
**Result:**
179
197
180
-
### Providing an example response
181
-
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
+
182
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.
183
205
184
206
#### @response
185
207
You can provide an example response for a route by using the `@response` annotation with valid JSON:
@@ -201,7 +223,7 @@ public function show($id)
201
223
#### @transformer, @transformerCollection, and @transformerModel
202
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:
203
225
204
-
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.
205
227
2. Get an instance of the model from the Eloquent model factory
206
228
2. If the parameter is an Eloquent model, load the first from the database.
207
229
3. Create an instance using `new`.
@@ -239,11 +261,27 @@ public function showUser(int $id)
239
261
```
240
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.
241
263
242
-
#### 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
243
281
244
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.
245
283
246
-
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.
247
285
248
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):
249
287
@@ -262,10 +300,10 @@ APP_URL=http://yourapp.app
262
300
If you want to modify the content of your generated documentation, go ahead and edit the generated `index.md` file.
263
301
The default location of this file is: `public/docs/source/index.md`.
264
302
265
-
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.
266
304
267
305
```sh
268
-
$ php artisan apidoc:update
306
+
$ php artisan apidoc:rebuild
269
307
```
270
308
271
309
As an optional parameter, you can use `--location` to tell the update command where your documentation can be found.
0 commit comments