├── .styleci.yml ├── CHANGELOG.md ├── CONTRIBUTING.md ├── LICENSE.md ├── body_params_1.png ├── body_params_2.png ├── composer.json ├── config └── apidoc.php ├── dingo.composer.json ├── docs ├── _index.md ├── extending │ ├── _index.md │ └── plugins.md ├── getting-started │ ├── _index.md │ ├── configuration.md │ ├── documenting-your-api.md │ ├── generating-documentation.md │ ├── installation.md │ └── migrating.md └── under-the-hood │ ├── _index.md │ ├── architecture.md │ └── how-it-works.md ├── phpstan.neon ├── resources └── views │ ├── documentarian.blade.php │ └── partials │ ├── example-requests │ ├── bash.blade.php │ ├── javascript.blade.php │ ├── php.blade.php │ └── python.blade.php │ ├── frontmatter.blade.php │ ├── info.blade.php │ └── route.blade.php ├── routes └── laravel.php └── src ├── ApiDoc.php ├── ApiDocGeneratorServiceProvider.php ├── Commands ├── GenerateDocumentation.php └── RebuildDocumentation.php ├── Extracting ├── Generator.php ├── ParamHelpers.php ├── RouteDocBlocker.php └── Strategies │ ├── BodyParameters │ └── GetFromBodyParamTag.php │ ├── Metadata │ └── GetFromDocBlocks.php │ ├── QueryParameters │ └── GetFromQueryParamTag.php │ ├── RequestHeaders │ └── GetFromRouteRules.php │ ├── Responses │ ├── ResponseCalls.php │ ├── UseApiResourceTags.php │ ├── UseResponseFileTag.php │ ├── UseResponseTag.php │ └── UseTransformerTags.php │ ├── Strategy.php │ └── UrlParameters │ └── GetFromUrlParamTag.php ├── Http └── Controller.php ├── Matching ├── LumenRouteAdapter.php ├── RouteMatcher.php ├── RouteMatcher │ └── Match.php └── RouteMatcherInterface.php ├── Tools ├── DocumentationConfig.php ├── Flags.php └── Utils.php └── Writing ├── PostmanCollectionWriter.php └── Writer.php /.styleci.yml: -------------------------------------------------------------------------------- 1 | preset: psr12 2 | 3 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | All notable changes to this project will be documented in this file. 3 | 4 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 5 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). 6 | 7 | ## Unreleased 8 | ### Added 9 | 10 | ### Changed 11 | 12 | ### Fixed 13 | 14 | ### Removed 15 | 16 | ## 4.8.0 - Saturday, 2 May 2020 ([compare to previous](https://github.com/mpociot/laravel-apidoc-generator/compare/4.7.0...4.8.0)) 17 | ### Added 18 | - Support @hideFromAPIDocumentation on controllers. (https://github.com/mpociot/laravel-apidoc-generator/pull/745) 19 | - Allow strategies to return null. (https://github.com/mpociot/laravel-apidoc-generator/pull/739) 20 | 21 | ## 4.7.0 - Sunday, 12 April 2020 ([compare to previous](https://github.com/mpociot/laravel-apidoc-generator/compare/4.6.0...4.7.0)) 22 | ### Added 23 | - Support for Laravel Vapor. (https://github.com/mpociot/laravel-apidoc-generator/pull/729) 24 | - Allow customization of static output path. (https://github.com/mpociot/laravel-apidoc-generator/pull/730) 25 | 26 | ## 4.6.0 - Wednesday, 8 April 2020 ([compare to previous](https://github.com/mpociot/laravel-apidoc-generator/compare/4.5.1...4.6.0)) 27 | ### Added 28 | - Allow `@authenticated` to be set at controller level. (https://github.com/mpociot/laravel-apidoc-generator/pull/726) 29 | 30 | ## 4.5.1 - Saturday, 4 April 2020 ([compare to previous](https://github.com/mpociot/laravel-apidoc-generator/compare/4.5.0...4.5.1)) 31 | ### Fixed 32 | - Fix version constraint...again. (https://github.com/mpociot/laravel-apidoc-generator/pull/725) 33 | 34 | ## 4.5.0 - Tuesday, 31 March 2020 ([compare to previous](https://github.com/mpociot/laravel-apidoc-generator/compare/4.4.3...4.5.0)) 35 | ### Fixed 36 | - Fix version constraints preventing installation on some Laravel 7 installations. 37 | 38 | ## 4.4.3 - Thursday, 26 March 2020 ([compare to previous](https://github.com/mpociot/laravel-apidoc-generator/compare/4.4.2...4.4.3)) 39 | ### Fixed 40 | - Fixed link to Postman connection in docs when Laravel autoload is used (https://github.com/mpociot/laravel-apidoc-generator/pull/714) 41 | 42 | ## 4.4.2 - Sunday, 21 March 2020 ([compare to previous](https://github.com/mpociot/laravel-apidoc-generator/compare/4.4.1...4.4.2)) 43 | ### Fixed 44 | - Fixed double json encode when fetching collection in Laravel type docs (https://github.com/mpociot/laravel-apidoc-generator/pull/713) 45 | 46 | 47 | ## 4.4.1 - Wednesday, 11 March 2020 ([compare to previous](https://github.com/mpociot/laravel-apidoc-generator/compare/4.4.0...4.4.1)) 48 | ### Added 49 | - Support for body params as array (https://github.com/mpociot/laravel-apidoc-generator/pull/710) 50 | 51 | ## 4.4.0 - Saturday, 7 March 2020 ([compare to previous](https://github.com/mpociot/laravel-apidoc-generator/compare/4.3.1...4.4.0)) 52 | ### Fixed 53 | - Array query params can now be used and render properly (https://github.com/mpociot/laravel-apidoc-generator/pull/700) 54 | 55 | ## 4.3.1 - Friday, 6 March 2020 ([compare to previous](https://github.com/mpociot/laravel-apidoc-generator/compare/4.3.0...4.3.1)) 56 | ### Changed 57 | - Updated Documentarian dependency for Laravel v7 (https://github.com/mpociot/laravel-apidoc-generator/pull/699) 58 | 59 | ## 4.3.0 - Saturday, 22 February 2020 ([compare to previous](https://github.com/mpociot/laravel-apidoc-generator/compare/4.2.4...4.3.0)) 60 | ### Changed 61 | - Updated nunomaduro/collision to include v4 (https://github.com/mpociot/laravel-apidoc-generator/pull/699) 62 | 63 | ### Fixed 64 | - Use correct protocol for Postman collcetion URL (https://github.com/mpociot/laravel-apidoc-generator/pull/697) 65 | 66 | ## [4.2.4] - Saturday, 15 February 2020 67 | ### Fixed 68 | - Shim URL::formatRoot() on Lumen (https://github.com/mpociot/laravel-apidoc-generator/pull/688) 69 | 70 | ## [4.2.3] - Tuesday, 4 February 2020 71 | ### Changed 72 | - Made "Skipping route" message more descriptive (https://github.com/mpociot/laravel-apidoc-generator/commit/6f61469a9fa8be30e7812cf622a7832163a08bb8) 73 | 74 | ## [4.2.2] - Tuesday, 21 January 2020 75 | ### Fixed 76 | - Set a default value for the routematcher when fetching from config (https://github.com/mpociot/laravel-apidoc-generator/pull/677) 77 | 78 | ## [4.2.1] - Monday, 20 January 2020 79 | ### Fixed 80 | - Fixed autogenerated docs endpoint address for Postman collection (https://github.com/mpociot/laravel-apidoc-generator/pull/673) 81 | 82 | ## [4.2.0] - Sunday, 19 January 2020 83 | ### Added 84 | - New Postman collection generation features (https://github.com/mpociot/laravel-apidoc-generator/pull/666): 85 | - Properly handle url parameters using the `:param` syntax (opposed to the Laravel-esque `{param}` syntax) 86 | - Allow configuring the auth section of Postman collection config 87 | - Add some documentation that was available but not exported in the Postman collection (for URL params and query params) 88 | 89 | ### Changed 90 | - The package can now create a documentation endpoint automatically for `laravel`-type routes. This also allows users to install the package on dev-only enviornments but have their routes available in others, without writing custom routing code. (https://github.com/mpociot/laravel-apidoc-generator/pull/659) 91 | 92 | ### Fixed 93 | - Error when installing due to DI not working properly on constructor (https://github.com/mpociot/laravel-apidoc-generator/pull/672) 94 | 95 | ## [4.1.0] - Monday, 6 January 2019 96 | ### Added 97 | - RouteMatcher to use can now be specified by user (https://github.com/mpociot/laravel-apidoc-generator/pull/657) 98 | 99 | ### Fixed 100 | - Also copy custom logo for non-static docs (https://github.com/mpociot/laravel-apidoc-generator/commit/720f9c9e9b2443bcfb474b959febaf6cf5c3f004) 101 | 102 | ## [4.0.2] - Monday, 25 November 2019 103 | ### Fixed 104 | - Fixed missing body parameters in response calls (https://github.com/mpociot/laravel-apidoc-generator/commit/5d9371c14391485630941c718d7f168afd540126) 105 | - Add slashes to header values in bash templates to escape special chars (https://github.com/mpociot/laravel-apidoc-generator/commit/e693d746b1c1daf342c28e53daa8f7b34ce9da2b) 106 | - Fixed iteration over null bug - set responses to empty array (https://github.com/mpociot/laravel-apidoc-generator/commit/a24b1e14b17ade8fb4aa1534448904e1075b004c) 107 | 108 | ## [4.0.1] - Monday, 16 November 2019 109 | ### Fixed 110 | - Update rebuild command to work with new docs locations (https://github.com/mpociot/laravel-apidoc-generator/pull/646) 111 | 112 | ## [4.0.0] - Thursday, 7 November 2019 113 | ### Added 114 | - Added `headers` stage (https://github.com/mpociot/laravel-apidoc-generator/pull/624) 115 | - Support for non-static docs, changed source files locations (https://github.com/mpociot/laravel-apidoc-generator/pull/608) 116 | - Support for Eloquent API resources (https://github.com/mpociot/laravel-apidoc-generator/pull/601) 117 | - `bindings` replaced by `@urlParam` annotation (https://github.com/mpociot/laravel-apidoc-generator/pull/599) 118 | - Better support for arrays and objects in bodyParams (https://github.com/mpociot/laravel-apidoc-generator/pull/597) 119 | 120 | ### Modified 121 | - Postman collection now have the body as `raw` instead of `formdata`. (https://github.com/mpociot/laravel-apidoc-generator/pull/627) 122 | - Nonexistent `@responseFile` annotations now show a warning and skip the route (https://github.com/mpociot/laravel-apidoc-generator/pull/620) 123 | - Use symfony/var-exporter to export PHP arrays, ensuring short array syntax (https://github.com/mpociot/laravel-apidoc-generator/pull/615) 124 | - Use single quotes in PHP example template (https://github.com/mpociot/laravel-apidoc-generator/pull/612) 125 | - Transformer annotations are now given priority over all other response strategies (https://github.com/mpociot/laravel-apidoc-generator/pull/620) 126 | - Made ResponseCalls strategy only execute if no successful responses exist. (https://github.com/mpociot/laravel-apidoc-generator/pull/605) 127 | - Hide null responses in examples. (https://github.com/mpociot/laravel-apidoc-generator/pull/605) 128 | - Made `responses` stage additive (https://github.com/mpociot/laravel-apidoc-generator/pull/605) 129 | - Renamed `query` and `body` in `response_calls` config to `queryParams` and `bodyParams` (https://github.com/mpociot/laravel-apidoc-generator/pull/603) 130 | 131 | ### Removed 132 | - Removed `apply.response_calls.headers` in favour of `apply.headers` (https://github.com/mpociot/laravel-apidoc-generator/pull/603) 133 | - Removed bindings in response_calls (https://github.com/mpociot/laravel-apidoc-generator/pull/599) 134 | 135 | ## [3.17.1] - Thursday, 12 September 2019 136 | ### Fixed 137 | - ResponseCalls: Call Lumen application correctly since it does not use HttpKernel (https://github.com/mpociot/laravel-apidoc-generator/pull/585) 138 | - Update usage of `clean*Parameters` in python template (https://github.com/mpociot/laravel-apidoc-generator/commit/02fb719d0d6c25e6ce72f30dc8b9604449061156) 139 | - Bugfix: *really* exclude parameters from examples, not just send empty strings (https://github.com/mpociot/laravel-apidoc-generator/commit/762e2e1003d389d6e785d31144eca89c40515926, https://github.com/mpociot/laravel-apidoc-generator/commit/e54b474578b53f97f4737664a63131b315aaf82d) 140 | 141 | ## [3.17.0] - Saturday, 7 September 2019 142 | ### Added 143 | - Switched to a plugin architecture that allows support for external strategies (https://github.com/mpociot/laravel-apidoc-generator/pull/570) 144 | 145 | ### Changed 146 | - Exclude Laravel Telescope routes when present (https://github.com/mpociot/laravel-apidoc-generator/pull/579) 147 | - Set status code for transformer response from tag if present (https://github.com/mpociot/laravel-apidoc-generator/pull/581) 148 | - Set status code for response call from actual response (https://github.com/mpociot/laravel-apidoc-generator/pull/581) 149 | 150 | ## [3.16.3] - Thursday, 5 September 2019 151 | ### Fixed 152 | - Removed references to removed helper functions in 6.0 (https://github.com/mpociot/laravel-apidoc-generator/pull/576) 153 | 154 | ## [3.16.2] - Wednesday, 4 September 2019 155 | ### Fixed 156 | - Support for Laravel 6 (https://github.com/mpociot/laravel-apidoc-generator/commit/f7dd8d19b75755763e8e20ab4025075eba5cd51a) 157 | 158 | ## [3.16.1] - Wednesday, 4 September 2019 159 | ### Added 160 | - Use HTTPS in Postman collection if base_url is HTTPS (https://github.com/mpociot/laravel-apidoc-generator/pull/575) 161 | 162 | ## [3.16.0] - Wednesday, 4 September 2019 163 | ### Added 164 | - Support for Laravel 6 (https://github.com/mpociot/laravel-apidoc-generator/pull/572) 165 | 166 | ## [3.15.0] - Saturday, 31 August 2019 167 | ### Added 168 | - Ability to exclude a query or body parameter from being included in the example requests (https://github.com/mpociot/laravel-apidoc-generator/pull/552) 169 | 170 | ## [3.14.0] - Saturday, 31 August 2019 171 | ### Fixed 172 | - Backwards compatibility for the changes to `@group` introduced in 3.12.0 (https://github.com/mpociot/laravel-apidoc-generator/commit/5647eda35ebb7f8aed35b31790c5f220b736e985) 173 | 174 | ## [3.13.0] (deleted) 175 | 176 | ## [3.12.0] - Sunday, 25 August 2019 177 | ### Fixed 178 | - Specifying an `@group` for a method no longer requires you to add the description. (https://github.com/mpociot/laravel-apidoc-generator/pull/556) 179 | - Pass the verbosity level down to the Collision library. (https://github.com/mpociot/laravel-apidoc-generator/pull/556) 180 | 181 | ## [3.11.0] - Friday, 9 August 2019 182 | ### Added 183 | - Support for query parameters in the bash template (https://github.com/mpociot/laravel-apidoc-generator/pull/545) 184 | - Include query parameters and headers in the generated Postman collection (https://github.com/mpociot/laravel-apidoc-generator/pull/537) 185 | - Include Python out of the box as example language (https://github.com/mpociot/laravel-apidoc-generator/pull/524) 186 | 187 | ### Changed 188 | - Moved nunomaduro/collision to "suggested" so it doesn't break PHP 7.0 (https://github.com/mpociot/laravel-apidoc-generator/commit/2f3a2144e1a4f1eb0229aea8b4d11707cb4aabbf) 189 | 190 | ### Fixed 191 | - Stopped using config helper inside config file (https://github.com/mpociot/laravel-apidoc-generator/pull/548) 192 | 193 | ## [3.10.0] - Sunday, 23 June 2019 194 | ### Added 195 | - `--verbose` flag to show exception encountered when making response calls (https://github.com/mpociot/laravel-apidoc-generator/commit/dc987f296e5a3d073f56c67911b2cb61ae47e9dc) 196 | 197 | ## [3.9.0] - Saturday, 8 June 2019 198 | ### Modified 199 | - Postman collections and URLs in example requests now use the `apidoc.base_url` config variable (https://github.com/mpociot/laravel-apidoc-generator/pull/523) 200 | 201 | ## [3.8.0] - Wednesday, 29 May 2019 202 | ### Added 203 | - Support for PHP array callable syntax in route action (https://github.com/mpociot/laravel-apidoc-generator/pull/516) 204 | 205 | ## [3.7.3] - Thursday, 23 May 2019 206 | ### Fixed 207 | - Added faker_seed (https://github.com/mpociot/laravel-apidoc-generator/commit/d2901e51a68c17066d4dd96054ff5bfdf124945b) 208 | 209 | ## [3.7.2] - Sunday, 19 May 2019 210 | ### Added 211 | - Support for URL paths in include/exclude rules (https://github.com/mpociot/laravel-apidoc-generator/pull/507) 212 | 213 | ## [3.7.1] - Friday, 17 May 2019 214 | ### Fixed 215 | - Handle exception for no URL::forceRootURL() method in Lumen (https://github.com/mpociot/laravel-apidoc-generator/commit/2146fa114dc18bc32c00b5c5550266d753d5aef3) 216 | - Url parameter bindings (https://github.com/mpociot/laravel-apidoc-generator/commit/f0dc118c6b7792894bf9baa352d7fc4ca8ca74b5) 217 | 218 | ## [3.7.0] - Thursday, 2 May 2019 219 | ### Added 220 | - Support for `@queryParams` in Dingo FormRequests (https://github.com/mpociot/laravel-apidoc-generator/pull/506) 221 | - Easier customisation of example languages (https://github.com/mpociot/laravel-apidoc-generator/commit/0aa737a2e54a913eab4d024a1644c5ddd5dee8b8) 222 | - Include PHP as example language (https://github.com/mpociot/laravel-apidoc-generator/commit/c5814762fa52095fe645716554839b6ae110ef89) 223 | 224 | ## [3.6.0] - Monday, 29 April 2019 225 | ### Added 226 | - Support for `@queryParams` in FormRequests (https://github.com/mpociot/laravel-apidoc-generator/pull/504) 227 | - Added `default_group` key to replace `ungrouped_name` (https://github.com/mpociot/laravel-apidoc-generator/commit/72b5f546c1b84e69fe43c720a04f448c3b96e345) 228 | 229 | ## [3.5.0] - Tuesday, 23 April 2019 230 | ### Added 231 | - Option to seed faker for deterministic output (https://github.com/mpociot/laravel-apidoc-generator/pull/503) 232 | - Support for binding prefixes (https://github.com/mpociot/laravel-apidoc-generator/pull/498) 233 | - Ability to override Laravel `config` (https://github.com/mpociot/laravel-apidoc-generator/pull/496) 234 | - Allow override of the name 'general' for ungrouped routes (https://github.com/mpociot/laravel-apidoc-generator/pull/491) 235 | 236 | ### Changed 237 | - Use parameter-bound URL in doc examples (https://github.com/mpociot/laravel-apidoc-generator/pull/500) 238 | 239 | ### Fixed 240 | - Request router now matches when router has sub-domain (https://github.com/mpociot/laravel-apidoc-generator/pull/493) 241 | 242 | ## [3.4.4] - Saturday, 30 March 2019 243 | ### Fixed 244 | - Allow users specify custom Content-type header for Markdown examples (https://github.com/mpociot/laravel-apidoc-generator/pull/486) 245 | 246 | ## [3.4.3] - Wednesday, 13 March 2019 247 | ### Fixed 248 | - Ignore scalar type hints when checking for FormRequests (https://github.com/mpociot/laravel-apidoc-generator/pull/474) 249 | 250 | ## [3.4.2] - Sunday, 10 March 2019 251 | ### Added 252 | - Ability to set cookies on response calls (https://github.com/mpociot/laravel-apidoc-generator/pull/471) 253 | 254 | ## [3.4.1] - Monday, 4 March 2019 255 | ### Fixed 256 | - Support for Lumen 5.7 (https://github.com/mpociot/laravel-apidoc-generator/pull/467) 257 | 258 | ## [3.4.0] - Wednesday, 27 February 2019 259 | ### Added 260 | - Support for Laravel 5.8 (https://github.com/mpociot/laravel-apidoc-generator/pull/462) 261 | - Ability to annotate body parameters on FormRequest (https://github.com/mpociot/laravel-apidoc-generator/pull/460) 262 | 263 | 264 | ## [3.3.2] - Tuesday, 12 February 2019 265 | ### Added 266 | - Ability to specify array and object body/query params using dot notation (https://github.com/mpociot/laravel-apidoc-generator/pull/445) 267 | - Ability to specify name and description of Postman collection (https://github.com/mpociot/laravel-apidoc-generator/pull/443) 268 | 269 | ### Fixed 270 | - Postman collection and documentation base URL now uses `config('app.url')` (https://github.com/mpociot/laravel-apidoc-generator/pull/458) 271 | 272 | ## [3.3.1] - Tuesday, 8 January 2019 273 | ### Fixed 274 | - Fixed vendor tags (https://github.com/mpociot/laravel-apidoc-generator/pull/444) 275 | 276 | ## [3.3.0] - Wednesday, 2 January 2019 277 | ### Added 278 | - Ability to replace json key values in response file (https://github.com/mpociot/laravel-apidoc-generator/pull/434) 279 | - Support for custom transfer serializers (https://github.com/mpociot/laravel-apidoc-generator/pull/441) 280 | 281 | ## [3.2.0] - Wednesday, 12 December 2018 282 | ### Changed 283 | - API groups are now sorted "naturally" (https://github.com/mpociot/laravel-apidoc-generator/pull/428) 284 | 285 | ### Fixed 286 | - Partial resource controllers are now properly supported (https://github.com/mpociot/laravel-apidoc-generator/pull/429) 287 | - PUT request body now formatted as `urlencoded` in Postman collection (https://github.com/mpociot/laravel-apidoc-generator/pull/418) 288 | - `@responseFile` strategy now properly renders responses (https://github.com/mpociot/laravel-apidoc-generator/pull/427) 289 | 290 | ## [3.1.1] - Wednesday, 5 December 2018 291 | ### Added 292 | - Ability to specify different responses for different status codes. (https://github.com/mpociot/laravel-apidoc-generator/pull/416) 293 | 294 | ## [3.1.0] - Wednesday, 28 November 2018 295 | ### Added 296 | - Add `ResponseFileStrategy` to retrieve responses from files. (https://github.com/mpociot/laravel-apidoc-generator/pull/410) 297 | 298 | ### Modified 299 | - Switch from `jQuery` to `fetch` in JavaScript examples. (https://github.com/mpociot/laravel-apidoc-generator/pull/411) 300 | 301 | ## [3.0.6] - Saturday, 24 November 2018 302 | ### Added 303 | - `include` and `exclude` route options now support wildcards (https://github.com/mpociot/laravel-apidoc-generator/pull/409) 304 | 305 | ## [3.0.5] - Thursday, 15 November 2018 306 | ### Fixed 307 | - Make `router` option case-insensitive (https://github.com/mpociot/laravel-apidoc-generator/pull/407) 308 | 309 | ## [3.0.4] - Wednesday, 7 November 2018 310 | ### Fixed 311 | - Replaced use of `Storage::copy` with PHP's `copy` to work with absolute paths (https://github.com/mpociot/laravel-apidoc-generator/pull/404) 312 | 313 | ## [3.0.3] - Friday, 2 November 2018 314 | ### Fixed 315 | - Replaced use of `config_path` with more generic option for better Lumen compatibility (https://github.com/mpociot/laravel-apidoc-generator/pull/398) 316 | 317 | ## [3.0.2] - Friday, 26 October 2018 318 | ### Added 319 | - Ability to specify examples for body and query parameters (https://github.com/mpociot/laravel-apidoc-generator/pull/394) 320 | ### Fixed 321 | - Rendering of example requests' descriptions (https://github.com/mpociot/laravel-apidoc-generator/pull/393) 322 | 323 | ## [3.0.1] - Monday, 22 October 2018 324 | ### Fixed 325 | - Rendering of query parameters' descriptions (https://github.com/mpociot/laravel-apidoc-generator/pull/387) 326 | 327 | ## [3.0] - Sunday, 21 October 2018 328 | ### Added 329 | - Official Lumen support (https://github.com/mpociot/laravel-apidoc-generator/pull/382) 330 | - `@queryParam` annotation (https://github.com/mpociot/laravel-apidoc-generator/pull/383) 331 | - `@bodyParam` annotation (https://github.com/mpociot/laravel-apidoc-generator/pull/362, https://github.com/mpociot/laravel-apidoc-generator/pull/366) 332 | - `@authenticated` annotation (https://github.com/mpociot/laravel-apidoc-generator/pull/369) 333 | - Ability to override the controller `@group` from the method. (https://github.com/mpociot/laravel-apidoc-generator/pull/372) 334 | - Ability to use a custom logo (https://github.com/mpociot/laravel-apidoc-generator/pull/368) 335 | 336 | ### Changed 337 | - Moved from command-line options to a config file (https://github.com/mpociot/laravel-apidoc-generator/pull/362) 338 | - Commands have been renamed to the `apidoc` namespace (previously `api`). (https://github.com/mpociot/laravel-apidoc-generator/pull/350) 339 | - 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) 340 | - `@resource` renamed to `@group` (https://github.com/mpociot/laravel-apidoc-generator/pull/371) 341 | - Added more configuration options for response calls (https://github.com/mpociot/laravel-apidoc-generator/pull/377) 342 | 343 | ### Fixed 344 | 345 | ### Removed 346 | - FormRequest parsing is no longer supported (https://github.com/mpociot/laravel-apidoc-generator/pull/362) 347 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | Contributions are welcome. 4 | 5 | ## Etiquette 6 | 7 | This project is open source, and as such, the maintainers give their free time to build and maintain the source code 8 | held within. They make the code freely available in the hope that it will be of use to other developers. It would be 9 | extremely unfair for them to suffer abuse or anger for their hard work. 10 | 11 | Please be considerate towards maintainers when raising issues or presenting pull requests. Let's show the 12 | world that developers are civilized and selfless people. 13 | 14 | It's the duty of the maintainer to ensure that all submissions to the project are of sufficient 15 | quality to benefit the project. Many developers have different skillsets, strengths, and weaknesses. Respect the maintainer's decision, and do not be upset or abusive if your submission is not used. 16 | 17 | ## Viability 18 | 19 | When requesting or submitting new features, first consider whether it might be useful to others. Open 20 | source projects are used by many developers, who may have entirely different needs to your own. Think about 21 | whether or not your feature is likely to be used by other users of the project. 22 | 23 | ## Procedure 24 | 25 | Before filing an issue: 26 | 27 | - Attempt to replicate the problem, to ensure that it wasn't a coincidental incident. 28 | - Check to make sure your feature suggestion isn't already present within the project. 29 | - Check the pull requests tab to ensure that the bug doesn't have a fix in progress. 30 | - Check the pull requests tab to ensure that the feature isn't already in progress. 31 | 32 | Before submitting a pull request: 33 | 34 | - Check the codebase to ensure that your feature doesn't already exist. 35 | - Check the pull requests to ensure that another person hasn't already submitted the feature or fix. 36 | 37 | ## Requirements 38 | 39 | - If your contribution changes the look of the generated documentation in some way, please include "before" and "after" screenshots in your pull request. 40 | 41 | - Add a description to your pull request so the reviewer knows what to look out for before looking through your changes 42 | 43 | - **Add tests!** - Your patch won't be accepted if it doesn't have tests. 44 | 45 | - **Document any change in behaviour** - Make sure the `README.md` and any other relevant documentation are kept up-to-date. 46 | 47 | - **One pull request per feature** - If you want to do more than one thing, send multiple pull requests. 48 | 49 | **Happy coding**! 50 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2016 Marcel Pociot 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in 13 | all copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 21 | THE SOFTWARE. 22 | -------------------------------------------------------------------------------- /body_params_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mpociot/laravel-apidoc-generator/80850863940fa6541c8d3d6e98ee18e9181f0a48/body_params_1.png -------------------------------------------------------------------------------- /body_params_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mpociot/laravel-apidoc-generator/80850863940fa6541c8d3d6e98ee18e9181f0a48/body_params_2.png -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "mpociot/laravel-apidoc-generator", 3 | "license": "MIT", 4 | "description": "Generate beautiful API documentation from your Laravel application", 5 | "keywords": [ 6 | "API", 7 | "Documentation", 8 | "Laravel" 9 | ], 10 | "homepage": "http://github.com/mpociot/laravel-apidoc-generator", 11 | "authors": [ 12 | { 13 | "name": "Marcel Pociot", 14 | "email": "m.pociot@gmail.com" 15 | } 16 | ], 17 | "require": { 18 | "php": ">=7.2.0", 19 | "ext-json": "*", 20 | "fzaninotto/faker": "^1.8", 21 | "illuminate/console": "^5.7|^6.0|^7.0|^8.0", 22 | "illuminate/routing": "^5.7|^6.0|^7.0|^8.0", 23 | "illuminate/support": "^5.7|^6.0|^7.0|^8.0", 24 | "league/flysystem": "^1.0", 25 | "mpociot/documentarian": "^0.4.0", 26 | "mpociot/reflection-docblock": "^1.0.1", 27 | "nunomaduro/collision": "^3.0|^4.0|^5.0", 28 | "ramsey/uuid": "^3.8|^4.0", 29 | "symfony/var-exporter": "^4.0|^5.0" 30 | }, 31 | "require-dev": { 32 | "dms/phpunit-arraysubset-asserts": "^0.1.0", 33 | "laravel/lumen-framework": "^5.7|^6.0|^7.0|^8.0", 34 | "league/fractal": "^0.19.0", 35 | "orchestra/testbench": "^3.7|^4.0|^5.0", 36 | "phpstan/phpstan": "^0.11.15", 37 | "phpunit/phpunit": "^8.0" 38 | }, 39 | "suggest": { 40 | "league/fractal": "Required for transformers support" 41 | }, 42 | "autoload": { 43 | "psr-4": { 44 | "Mpociot\\ApiDoc\\": "src/" 45 | } 46 | }, 47 | "autoload-dev": { 48 | "psr-4": { 49 | "Mpociot\\ApiDoc\\Tests\\": "tests/" 50 | } 51 | }, 52 | "scripts": { 53 | "lint": "phpstan analyse -c ./phpstan.neon src", 54 | "test": "phpunit --stop-on-failure --exclude-group dingo", 55 | "test-ci": "phpunit --exclude-group dingo" 56 | }, 57 | "extra": { 58 | "laravel": { 59 | "providers": [ 60 | "Mpociot\\ApiDoc\\ApiDocGeneratorServiceProvider" 61 | ] 62 | }, 63 | "branch-alias": { 64 | "dev-v4": "4.x-dev" 65 | } 66 | }, 67 | "config": { 68 | "preferred-install": "dist", 69 | "sort-packages": true 70 | } 71 | } 72 | -------------------------------------------------------------------------------- /config/apidoc.php: -------------------------------------------------------------------------------- 1 | 'static', 11 | 12 | /* 13 | * Static output folder: HTML documentation and assets will be generated in this folder. 14 | */ 15 | 'output_folder' => 'public/docs', 16 | 17 | /* 18 | * Settings for `laravel` type output. 19 | */ 20 | 'laravel' => [ 21 | /* 22 | * Whether to automatically create a docs endpoint for you to view your generated docs. 23 | * If this is false, you can still set up routing manually. 24 | */ 25 | 'autoload' => false, 26 | 27 | /* 28 | * URL path to use for the docs endpoint (if `autoload` is true). 29 | * 30 | * By default, `/doc` opens the HTML page, and `/doc.json` downloads the Postman collection. 31 | */ 32 | 'docs_url' => '/doc', 33 | 34 | /* 35 | * Middleware to attach to the docs endpoint (if `autoload` is true). 36 | */ 37 | 'middleware' => [], 38 | ], 39 | 40 | /* 41 | * The router to be used (Laravel or Dingo). 42 | */ 43 | 'router' => 'laravel', 44 | 45 | /* 46 | * The storage to be used when generating assets. 47 | * By default, uses 'local'. If you are using Laravel Vapor, please use S3 and make sure 48 | * the correct bucket is correctly configured in the .env file 49 | */ 50 | 'storage' => 'local', 51 | 52 | /* 53 | * The base URL to be used in examples and the Postman collection. 54 | * By default, this will be the value of config('app.url'). 55 | */ 56 | 'base_url' => null, 57 | 58 | /* 59 | * Generate a Postman collection in addition to HTML docs. 60 | * For 'static' docs, the collection will be generated to public/docs/collection.json. 61 | * For 'laravel' docs, it will be generated to storage/app/apidoc/collection.json. 62 | * The `ApiDoc::routes()` helper will add routes for both the HTML and the Postman collection. 63 | */ 64 | 'postman' => [ 65 | /* 66 | * Specify whether the Postman collection should be generated. 67 | */ 68 | 'enabled' => true, 69 | 70 | /* 71 | * The name for the exported Postman collection. Default: config('app.name')." API" 72 | */ 73 | 'name' => null, 74 | 75 | /* 76 | * The description for the exported Postman collection. 77 | */ 78 | 'description' => null, 79 | 80 | /* 81 | * The "Auth" section that should appear in the postman collection. See the schema docs for more information: 82 | * https://schema.getpostman.com/json/collection/v2.0.0/docs/index.html 83 | */ 84 | 'auth' => null, 85 | ], 86 | 87 | /* 88 | * The routes for which documentation should be generated. 89 | * Each group contains rules defining which routes should be included ('match', 'include' and 'exclude' sections) 90 | * and rules which should be applied to them ('apply' section). 91 | */ 92 | 'routes' => [ 93 | [ 94 | /* 95 | * Specify conditions to determine what routes will be parsed in this group. 96 | * A route must fulfill ALL conditions to pass. 97 | */ 98 | 'match' => [ 99 | 100 | /* 101 | * Match only routes whose domains match this pattern (use * as a wildcard to match any characters). 102 | */ 103 | 'domains' => [ 104 | '*', 105 | // 'domain1.*', 106 | ], 107 | 108 | /* 109 | * Match only routes whose paths match this pattern (use * as a wildcard to match any characters). 110 | */ 111 | 'prefixes' => [ 112 | '*', 113 | // 'users/*', 114 | ], 115 | 116 | /* 117 | * Match only routes registered under this version. This option is ignored for Laravel router. 118 | * Note that wildcards are not supported. 119 | */ 120 | 'versions' => [ 121 | 'v1', 122 | ], 123 | ], 124 | 125 | /* 126 | * Include these routes when generating documentation, 127 | * even if they did not match the rules above. 128 | * Note that the route must be referenced by name here (wildcards are supported). 129 | */ 130 | 'include' => [ 131 | // 'users.index', 'healthcheck*' 132 | ], 133 | 134 | /* 135 | * Exclude these routes when generating documentation, 136 | * even if they matched the rules above. 137 | * Note that the route must be referenced by name here (wildcards are supported). 138 | */ 139 | 'exclude' => [ 140 | // 'users.create', 'admin.*' 141 | ], 142 | 143 | /* 144 | * Specify rules to be applied to all the routes in this group when generating documentation 145 | */ 146 | 'apply' => [ 147 | /* 148 | * Specify headers to be added to the example requests 149 | */ 150 | 'headers' => [ 151 | 'Content-Type' => 'application/json', 152 | 'Accept' => 'application/json', 153 | // 'Authorization' => 'Bearer {token}', 154 | // 'Api-Version' => 'v2', 155 | ], 156 | 157 | /* 158 | * If no @response or @transformer declarations are found for the route, 159 | * we'll try to get a sample response by attempting an API call. 160 | * Configure the settings for the API call here. 161 | */ 162 | 'response_calls' => [ 163 | /* 164 | * API calls will be made only for routes in this group matching these HTTP methods (GET, POST, etc). 165 | * List the methods here or use '*' to mean all methods. Leave empty to disable API calls. 166 | */ 167 | 'methods' => ['GET'], 168 | 169 | /* 170 | * Laravel config variables which should be set for the API call. 171 | * This is a good place to ensure that notifications, emails 172 | * and other external services are not triggered 173 | * during the documentation API calls 174 | */ 175 | 'config' => [ 176 | 'app.env' => 'documentation', 177 | 'app.debug' => false, 178 | // 'service.key' => 'value', 179 | ], 180 | 181 | /* 182 | * Cookies which should be sent with the API call. 183 | */ 184 | 'cookies' => [ 185 | // 'name' => 'value' 186 | ], 187 | 188 | /* 189 | * Query parameters which should be sent with the API call. 190 | */ 191 | 'queryParams' => [ 192 | // 'key' => 'value', 193 | ], 194 | 195 | /* 196 | * Body parameters which should be sent with the API call. 197 | */ 198 | 'bodyParams' => [ 199 | // 'key' => 'value', 200 | ], 201 | ], 202 | ], 203 | ], 204 | ], 205 | 206 | 'strategies' => [ 207 | 'metadata' => [ 208 | \Mpociot\ApiDoc\Extracting\Strategies\Metadata\GetFromDocBlocks::class, 209 | ], 210 | 'urlParameters' => [ 211 | \Mpociot\ApiDoc\Extracting\Strategies\UrlParameters\GetFromUrlParamTag::class, 212 | ], 213 | 'queryParameters' => [ 214 | \Mpociot\ApiDoc\Extracting\Strategies\QueryParameters\GetFromQueryParamTag::class, 215 | ], 216 | 'headers' => [ 217 | \Mpociot\ApiDoc\Extracting\Strategies\RequestHeaders\GetFromRouteRules::class, 218 | ], 219 | 'bodyParameters' => [ 220 | \Mpociot\ApiDoc\Extracting\Strategies\BodyParameters\GetFromBodyParamTag::class, 221 | ], 222 | 'responses' => [ 223 | \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseTransformerTags::class, 224 | \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseResponseTag::class, 225 | \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseResponseFileTag::class, 226 | \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseApiResourceTags::class, 227 | \Mpociot\ApiDoc\Extracting\Strategies\Responses\ResponseCalls::class, 228 | ], 229 | ], 230 | 231 | /* 232 | * Custom logo path. The logo will be copied from this location 233 | * during the generate process. Set this to false to use the default logo. 234 | * 235 | * Change to an absolute path to use your custom logo. For example: 236 | * 'logo' => resource_path('views') . '/api/logo.png' 237 | * 238 | * If you want to use this, please be aware of the following rules: 239 | * - the image size must be 230 x 52 240 | */ 241 | 'logo' => false, 242 | 243 | /* 244 | * Name for the group of routes which do not have a @group set. 245 | */ 246 | 'default_group' => 'general', 247 | 248 | /* 249 | * Example requests for each endpoint will be shown in each of these languages. 250 | * Supported options are: bash, javascript, php, python 251 | * You can add a language of your own, but you must publish the package's views 252 | * and define a corresponding view for it in the partials/example-requests directory. 253 | * See https://laravel-apidoc-generator.readthedocs.io/en/latest/generating-documentation.html 254 | * 255 | */ 256 | 'example_languages' => [ 257 | 'bash', 258 | 'javascript', 259 | ], 260 | 261 | /* 262 | * Configure how responses are transformed using @transformer and @transformerCollection 263 | * Requires league/fractal package: composer require league/fractal 264 | * 265 | */ 266 | 'fractal' => [ 267 | /* If you are using a custom serializer with league/fractal, 268 | * you can specify it here. 269 | * 270 | * Serializers included with league/fractal: 271 | * - \League\Fractal\Serializer\ArraySerializer::class 272 | * - \League\Fractal\Serializer\DataArraySerializer::class 273 | * - \League\Fractal\Serializer\JsonApiSerializer::class 274 | * 275 | * Leave as null to use no serializer or return a simple JSON. 276 | */ 277 | 'serializer' => null, 278 | ], 279 | 280 | /* 281 | * If you would like the package to generate the same example values for parameters on each run, 282 | * set this to any number (eg. 1234) 283 | * 284 | */ 285 | 'faker_seed' => null, 286 | 287 | /* 288 | * If you would like to customize how routes are matched beyond the route configuration you may 289 | * declare your own implementation of RouteMatcherInterface 290 | * 291 | */ 292 | 'routeMatcher' => \Mpociot\ApiDoc\Matching\RouteMatcher::class, 293 | ]; 294 | -------------------------------------------------------------------------------- /dingo.composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "mpociot/laravel-apidoc-generator", 3 | "license": "MIT", 4 | "description": "Generate beautiful API documentation from your Laravel application", 5 | "keywords": [ 6 | "API", 7 | "Documentation", 8 | "Laravel" 9 | ], 10 | "homepage": "http://github.com/mpociot/laravel-apidoc-generator", 11 | "authors": [ 12 | { 13 | "name": "Marcel Pociot", 14 | "email": "m.pociot@gmail.com" 15 | } 16 | ], 17 | "require": { 18 | "php": ">=7.2.0", 19 | "ext-json": "*", 20 | "fzaninotto/faker": "^1.8", 21 | "illuminate/console": "^5.7|^6.0|^7.0|^8.0", 22 | "illuminate/routing": "^5.7|^6.0|^7.0|^8.0", 23 | "illuminate/support": "^5.7|^6.0|^7.0|^8.0", 24 | "league/flysystem": "^1.0", 25 | "mpociot/documentarian": "^0.4.0", 26 | "mpociot/reflection-docblock": "^1.0.1", 27 | "nunomaduro/collision": "^3.0|^4.0|^5.0", 28 | "ramsey/uuid": "^3.8|^4.0", 29 | "symfony/var-exporter": "^4.0|^5.0" 30 | }, 31 | "require-dev": { 32 | "dingo/api": "^2.3", 33 | "dms/phpunit-arraysubset-asserts": "^0.1.0", 34 | "league/fractal": "^0.17.0", 35 | "orchestra/testbench": "^3.7|^4.0|^5.0", 36 | "phpstan/phpstan": "^0.11.15", 37 | "phpunit/phpunit": "^8.0" 38 | }, 39 | "suggest": { 40 | "league/fractal": "Required for transformers support" 41 | }, 42 | "autoload": { 43 | "psr-4": { 44 | "Mpociot\\ApiDoc\\": "src/" 45 | } 46 | }, 47 | "autoload-dev": { 48 | "psr-4": { 49 | "Mpociot\\ApiDoc\\Tests\\": "tests/" 50 | } 51 | }, 52 | "scripts": { 53 | "lint": "phpstan analyse -c ./phpstan.neon src", 54 | "test": "phpunit --stop-on-failure --group dingo", 55 | "test-ci": "phpunit --group dingo" 56 | }, 57 | "extra": { 58 | "laravel": { 59 | "providers": [ 60 | "Mpociot\\ApiDoc\\ApiDocGeneratorServiceProvider" 61 | ] 62 | }, 63 | "branch-alias": { 64 | "dev-v4": "4.x-dev" 65 | } 66 | }, 67 | "config": { 68 | "preferred-install": "dist", 69 | "sort-packages": true 70 | } 71 | } 72 | -------------------------------------------------------------------------------- /docs/_index.md: -------------------------------------------------------------------------------- 1 | --- 2 | packageName: Laravel API Documentation Generator 3 | githubUrl: https://github.com/mpociot/laravel-apidoc-generator 4 | --- -------------------------------------------------------------------------------- /docs/extending/_index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Extending 3 | order: 2 4 | --- 5 | -------------------------------------------------------------------------------- /docs/extending/plugins.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Plugins 3 | order: 1 4 | --- 5 | # Extending functionality with plugins 6 | You can use plugins to alter how the Generator fetches data about your routes. For instance, suppose all your routes have a body parameter `organizationId`, and you don't want to annotate this with `@queryParam` on each method. You can create a plugin that adds this to all your body parameters. Let's see how to do this. 7 | 8 | ## The stages of route processing 9 | Route processing is performed in six stages: 10 | - metadata (this covers route `title`, route `description`, route `groupName`, route `groupDescription`, and authentication status (`authenticated`)) 11 | - urlParameters 12 | - queryParameters 13 | - headers (headers to be added to example request and response calls) 14 | - bodyParameters 15 | - responses 16 | 17 | For each stage, the Generator attempts the specified strategies to fetch data. The Generator will call of the strategies configured, progressively combining their results together before to produce the final output of that stage. 18 | 19 | There are a number of strategies included with the package, so you don't have to set up anything to get it working. 20 | 21 | > Note: The included ResponseCalls strategy is designed to stop if a response with a 2xx status code has already been gotten via any other strategy. 22 | 23 | ## Strategies 24 | To create a strategy, create a class that extends `\Mpociot\ApiDoc\Extracting\Strategies\Strategy`. 25 | 26 | The `__invoke` method of the strategy is where you perform your actions and return data. It receives the following arguments: 27 | - the route (instance of `\Illuminate\Routing\Route`) 28 | - the controller class handling the route (`\ReflectionClass`) 29 | - the controller method (`\ReflectionMethod $method`) 30 | - the rules specified in the apidoc.php config file for the group this route belongs to, under the `apply` section (array) 31 | - the context. This contains all data for the route that has been parsed thus far in the previous stages. This means, by the `responses` stage, the context will contain the following keys: `metadata`, `bodyParameters` and `queryParameters`. 32 | 33 | Here's what your strategy in our example would look like: 34 | 35 | ```php 36 | use Illuminate\Routing\Route; 37 | use Mpociot\ApiDoc\Extracting\Strategies\Strategy; 38 | 39 | class AddOrganizationIdBodyParameter extends Strategy 40 | { 41 | public function __invoke(Route $route, \ReflectionClass $controller, \ReflectionMethod $method, array $routeRules, array $context = []) 42 | { 43 | return [ 44 | 'organizationId' => [ 45 | 'type' => 'integer', 46 | 'description' => 'The ID of the organization', 47 | 'required' => true, 48 | 'value' => 2, 49 | ] 50 | ]; 51 | } 52 | } 53 | ``` 54 | 55 | The last thing to do is to register the strategy. Strategies are registered in a `strategies` key in the `apidoc.php` file. Here's what the file looks like by default: 56 | 57 | ```php 58 | ... 59 | 'strategies' => [ 60 | 'metadata' => [ 61 | \Mpociot\ApiDoc\Extracting\Strategies\Metadata\GetFromDocBlocks::class, 62 | ], 63 | 'urlParameters' => [ 64 | \Mpociot\ApiDoc\Extracting\Strategies\UrlParameters\GetFromUrlParamTag::class, 65 | ], 66 | 'queryParameters' => [ 67 | \Mpociot\ApiDoc\Extracting\Strategies\QueryParameters\GetFromQueryParamTag::class, 68 | ], 69 | 'headers' => [ 70 | \Mpociot\ApiDoc\Extracting\Strategies\RequestHeaders\GetFromRouteRules::class, 71 | ], 72 | 'bodyParameters' => [ 73 | \Mpociot\ApiDoc\Extracting\Strategies\BodyParameters\GetFromBodyParamTag::class, 74 | ], 75 | 'responses' => [ 76 | \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseTransformerTags::class, 77 | \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseResponseTag::class, 78 | \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseResponseFileTag::class, 79 | \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseApiResourceTags::class, 80 | \Mpociot\ApiDoc\Extracting\Strategies\Responses\ResponseCalls::class, 81 | ], 82 | ], 83 | ... 84 | ``` 85 | 86 | You can add, replace or remove strategies from here. In our case, we're adding our bodyParameter strategy: 87 | 88 | ```php 89 | 90 | 'bodyParameters' => [ 91 | \Mpociot\ApiDoc\Extracting\Strategies\BodyParameters\GetFromBodyParamTag::class, 92 | AddOrganizationIdBodyParameter::class, 93 | ], 94 | ``` 95 | 96 | And we're done. Now, when we run `php artisan docs:generate`, all our routes will have this bodyParameter added. 97 | 98 | 99 | We could go further and modify our strategy so it doesn't add this parameter if the route is a GET route or is authenticated: 100 | 101 | ```php 102 | public function __invoke(Route $route, \ReflectionClass $controller, \ReflectionMethod $method, array $routeRules, array $context = []) 103 | { 104 | if (in_array('GET', $route->methods()) { 105 | return null; 106 | } 107 | 108 | if ($context['metadata']['authenticated']) { 109 | return null; 110 | } 111 | 112 | return [ 113 | 'organizationId' => [ 114 | 'type' => 'integer', 115 | 'description' => 'The ID of the organization', 116 | 'required' => true, 117 | 'value' => 2, 118 | ] 119 | ]; 120 | } 121 | ``` 122 | 123 | > Note: If you would like a parameter (body or query) to be included in the documentation but excluded from examples, set its `value` property to `null`. 124 | 125 | The strategy class also has access to the current apidoc configuration via its `config` property. For instance, you can retrieve the default group with `$this->config->get('default_group')`. 126 | 127 | You are also provided with the instance pproperty `stage`, which is set to the name of the currently executing stage. 128 | 129 | 130 | ## Utilities 131 | You have access to a number of tools when developing strategies. They include: 132 | 133 | - The `RouteDocBlocker` class (in the `\Mpociot\ApiDoc\Extracting` namespace) has a single public static method, `getDocBlocksFromRoute(Route $route)`. It allows you to retrieve the docblocks for a given route. It returns an array of with two keys: `method` and `class` containing the docblocks for the method and controller handling the route respectively. Both are instances of `\Mpociot\Reflection\DocBlock`. 134 | 135 | - The `ParamsHelper` trait (in the `\Mpociot\ApiDoc\Extracting` namespace) can be included in your strategies. It contains a number of useful methods for working with parameters, including type casting and generating dummy values. 136 | 137 | ## API 138 | Each strategy class must implement the __invoke method with the parameters as described above. This method must return the needed data for the intended stage, or `null` to indicate failure. 139 | - In the `metadata` stage, strategies should return an array. These are the expected keys (you may omit some, or all): 140 | 141 | ``` 142 | 'groupName' 143 | 'groupDescription' 144 | 'title' 145 | 'description' 146 | 'authenticated' // boolean 147 | ``` 148 | 149 | - In the `bodyParameters` and `queryParameters` stages, you can return an array with arbitrary keys. These keys will serve as the names of your parameters. Array keys can be indicated with Laravel's dot notation. The value of each key should be an array with the following keys: 150 | 151 | ``` 152 | 'type', // Only valid in bodyParameters 153 | 'description', 154 | 'required', // boolean 155 | 'value', // An example value for the parameter 156 | ``` 157 | - In the `responses` stage, your strategy should return an array containing the responses for different status codes. Each item in the array should be an array representing the response with a `status` key containing the HTTP status code, and a `content` key a string containing the response. For example: 158 | 159 | ```php 160 | 161 | public function __invoke(Route $route, \ReflectionClass $controller, \ReflectionMethod $method, array $routeRules, array $context = []) 162 | { 163 | return [ 164 | [ 165 | 'content' => "Haha", 166 | 'status' => 201 167 | ], 168 | [ 169 | 'content' => "Nope", 170 | 'status' => 404 171 | ], 172 | ] 173 | } 174 | ``` 175 | 176 | Responses are _additive_. This means all the responses returned from each stage are added to the `responses` array. But note that the `ResponseCalls` strategy will only attempt to fetch a response if there are no responses with a status code of 2xx already. 177 | 178 | - In the `headers` stage, you can return an array of headers. You may also negate existing headers by providing `false` as the header value. 179 | -------------------------------------------------------------------------------- /docs/getting-started/_index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Getting Started 3 | order: 1 4 | --- 5 | -------------------------------------------------------------------------------- /docs/getting-started/configuration.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Configuration 3 | order: 2 4 | --- 5 | # Configuration 6 | 7 | Before you can generate your documentation, you'll need to configure a few things in your `config/apidoc.php` file. 8 | 9 | If you aren't sure what an option does, it's best to leave it set to the default. 10 | 11 | ## type 12 | This is the type of documentation output to generate. 13 | 14 | `static` will generate a static HTML page in the `public/docs` folder, so anyone can visit your documentation page by going to {yourapp.domain}/docs. 15 | 16 | `laravel` will generate the documentation as a Blade view within the `resources/views/apidoc` folder, so you can add routing and authentication to your liking. 17 | 18 | > In both instances, the source markdown file will be generated in `resources/docs/source`. 19 | 20 | ### laravel 21 | If you're using `laravel` type output, this package can automatically set up an endpoint for you to view your generated docs. You can configure this here. 22 | 23 | ### autoload 24 | Set this to `true` if you want the documentation endpoint to be automatically set up for you. Default: `false` 25 | 26 | You may, of course, use your own routing instead of using `autoload`. 27 | 28 | ### docs_url 29 | The path for the documentation endpoint (if `autoload` is true). Your Postman collection (if you have that enabled) will be at this path + '.json' (eg `/doc.json`). Default: `/doc` 30 | 31 | > Note: There is currently a known issue with using `/docs` as the path for `laravel` docs. You should not use it, as it conflicts with the folder structure in the `public` folder and may confuse the webserver. 32 | 33 | ## middleware 34 | Here, you can specify middleware to be attached to the documentation endpoint (if `autoload` is true). 35 | 36 | ## router 37 | The router to use when processing your routes (can be Laravel or Dingo. Defaults to **Laravel**) 38 | 39 | ## base_url 40 | The base URL to be used in examples and the Postman collection. By default, this will be the value of config('app.url'). 41 | 42 | ## postman 43 | 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. 44 | 45 | For `static` docs (see [type](#type)), the collection will be created in `public/docs/collection.json`, so it can be accessed by visiting {yourapp.domain}/docs/colllection.json. 46 | 47 | For `laravel` docs, the collection will be generated to `storage/app/apidoc/collection.json`. The `ApiDoc::routes()` helper will add a `/docs.json` endpoint to fetch it.. 48 | 49 | ### enabled 50 | Whether or not to generate a Postman API collection. Default: **true** 51 | 52 | ### name 53 | The name for the exported Postman collection. If you leave this as null, this package will default to `config('app.name')." API"`. 54 | 55 | ### description 56 | The description for the generated Postman collection. 57 | 58 | ## logo 59 | 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: 60 | ``` 61 | 'logo' => resource_path('views') . '/api/logo.png' 62 | ``` 63 | 64 | If you want to use this, please note that the image size must be 230 x 52. 65 | 66 | ## default_group 67 | When [documenting your api](/docs/laravel-apidoc-generator/getting-started/documenting-your-api), you use `@group` annotations to group API endpoints. Endpoints which do not have a group annotation will be grouped under the `default_group`. Defaults to **"general"**. 68 | 69 | ## example_languages 70 | For each endpoint, an example request is shown in each of the languages specified in this array. Currently only `bash`, `javascript`, `php` and `python` are supported. You can add your own language, but you must also define the corresponding view (see [Specifying languages for examples](/docs/laravel-apidoc-generator/getting-started/generating-documentation)). Default: `["bash", "javascript"]` 71 | 72 | ## faker_seed 73 | 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.](/docs/laravel-apidoc-generator/getting-started/documenting-your-api)) 74 | 75 | ## routeMatcher 76 | The route matcher class provides the algorithm that determines what routes should be documented. The default matcher used is the included `\Mpociot\ApiDoc\Matching\RouteMatcher::class`, and you can provide your own custom implementation if you wish to programmatically change the algorithm. The provided matcher must be an instance of the `RouteMatcherInterface`. 77 | 78 | ## fractal 79 | 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. 80 | 81 | > Note: using transformers requires league/fractal package. Run `composer require league/fractal to install 82 | 83 | 84 | ### serializer 85 | If you are using a custom serializer with league/fractal, you can specify it here. league/fractal comes with the following serializers: 86 | - \League\Fractal\Serializer\ArraySerializer::class 87 | - \League\Fractal\Serializer\DataArraySerializer::class 88 | - \League\Fractal\Serializer\JsonApiSerializer::class 89 | 90 | Leave this as null to use no serializer or return a simple JSON. 91 | 92 | ## routes 93 | 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. 94 | 95 | > 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. 96 | 97 | 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 demonstrate them: 98 | 99 | ```php 100 | Route::group(['domain' => 'api.acme.co'], function () { 101 | Route::get('/apps', 'AppController@listApps') 102 | ->name('apps.list'); 103 | Route::get('/apps/{id}', 'AppController@getApp') 104 | ->name('apps.get'); 105 | Route::post('/apps', 'AppController@createApp') 106 | ->name('apps.create'); 107 | Route::get('/users', 'UserController@listUsers') 108 | ->name('users.list'); 109 | Route::get('/users/{id}', 'UserController@getUser') 110 | ->name('users.get'); 111 | }); 112 | 113 | Route::group(['domain' => 'public-api.acme.co'], function () { 114 | Route::get('/stats', 'PublicController@getStats') 115 | ->name('public.stats'); 116 | }); 117 | 118 | Route::group(['domain' => 'status.acme.co'], function () { 119 | Route::get('/status', 'PublicController@getStatus') 120 | ->name('status'); 121 | }); 122 | ``` 123 | 124 | ### match 125 | 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): 126 | 127 | ### domains 128 | 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 separate them into two groups like this: 129 | 130 | ```php 131 | return [ 132 | //..., 133 | 134 | 'routes' => [ 135 | [ 136 | 'match' => [ 137 | 'domains' => ['api.acme.co'], 138 | 'prefixes' => ['*'], 139 | ], 140 | 'apply' => [ 141 | 'headers' => [ 'Authorization' => 'Bearer {your-token}'] 142 | ] 143 | ], 144 | [ 145 | 'match' => [ 146 | 'domains' => ['public-api.acme.co', 'status.acme.co'], 147 | 'prefixes' => ['*'], 148 | ], 149 | ], 150 | ], 151 | ]; 152 | ``` 153 | 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. 154 | 155 | You can use the `*` wildcard to match all domains (or as a placeholder in a pattern). 156 | 157 | ### prefixes 158 | 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: 159 | 160 | ```php 161 | return [ 162 | //..., 163 | 164 | 'routes' => [ 165 | [ 166 | 'match' => [ 167 | 'domains' => ['*'], 168 | 'prefixes' => ['users/*', 'apps/*'], 169 | ], 170 | 'apply' => [ 171 | 'headers' => [ 'Authorization' => 'Bearer {your-token}'] 172 | ] 173 | ], 174 | [ 175 | 'match' => [ 176 | 'domains' => ['*'], 177 | 'prefixes' => ['stats/*', 'status/*'], 178 | ], 179 | ], 180 | ], 181 | ]; 182 | ``` 183 | 184 | 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.) 185 | 186 | > The `domains` and `prefixes` keys are both required for all route groups. 187 | 188 | ### versions 189 | > This section only applies if you're using Dingo Router 190 | 191 | 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: 192 | 193 | ```php 194 | return [ 195 | //..., 196 | 197 | 'routes' => [ 198 | [ 199 | 'match' => [ 200 | 'domains' => ['*'], 201 | 'prefixes' => ['*'], 202 | 'versions' => ['v1', 'beta'], // only if you're using Dingo router 203 | ], 204 | ], 205 | ], 206 | ]; 207 | ``` 208 | 209 | ### include and exclude 210 | 211 | The `include` key holds an array of patterns (route names or paths) which should be included in this group, *even if they do not match the rules in the match section*. 212 | 213 | The `exclude` key holds an array of patterns (route names or paths) which should be excluded from this group, *even if they match the rules in the match section*. 214 | 215 | Using our above sample routes, assuming you wanted to place the `users.list` route in the second group (no Authorization header), here's how you could do it: 216 | 217 | ```php 218 | return [ 219 | //..., 220 | 221 | 'routes' => [ 222 | [ 223 | 'match' => [ 224 | 'domains' => ['api.acme.co'], 225 | 'prefixes' => ['*'], 226 | ], 227 | 'exclude' => ['users.list'], 228 | 'apply' => [ 229 | 'headers' => [ 'Authorization' => 'Bearer {your-token}'] 230 | ] 231 | ], 232 | [ 233 | 'match' => [ 234 | 'domains' => ['public-api.acme.co', 'status.acme.co'], 235 | 'prefixes' => ['*'], 236 | ], 237 | 'include' => ['users.list'], 238 | ], 239 | ], 240 | ]; 241 | ``` 242 | 243 | These values support wildcards and paths, so you can have `'exclude' => ['users/*']` to exclude all routes with URLs matching the pattern. 244 | 245 | ### apply 246 | 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: 247 | 248 | ### headers 249 | Like we've demonstrated above, any headers you specify here will be added to the headers shown in the example requests in your documentation. They will also be included in ["response calls"](/docs/laravel-apidoc-generator/getting-started/documenting-your-api). Headers are specified as key => value strings. 250 | 251 | ### response_calls 252 | These are the settings that will be applied when making ["response calls"](/docs/laravel-apidoc-generator/getting-started/documenting-your-api). See the linked section for details. 253 | -------------------------------------------------------------------------------- /docs/getting-started/documenting-your-api.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Documenting Your API 3 | order: 4 4 | --- 5 | # Documenting Your API 6 | This package generates documentation from your code using mainly annotations (in doc block comments). 7 | 8 | ## Grouping endpoints 9 | All endpoints are grouped for easy organization. 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 table of contents shown in the sidebar. 10 | 11 | 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 `