Merge pull request #608 from mpociot/non-static-docs

Add options for non static docs

Author: shalvah

.gitignore

@@ -3,9 +3,13 @@ composer.lock
 .php_cs.cache
 /vendor/
 public/
+resources/docs/
+resources/views/apidoc/
 tests/public/
 .idea/
 coverage.xml
 results.xml
 docs/_build
 docs/make.bat
+tests/public/docs/
+tests/resources/**

CHANGELOG.md

@@ -15,9 +15,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [4.0.0] 
 ### Added
+- Support for Eloquent API resources (https://github.com/mpociot/laravel-apidoc-generator/pull/601)
 - `bindings` replaced by `@urlParam` annotation (https://github.com/mpociot/laravel-apidoc-generator/pull/599)
 - Better support for arrays and objects in bodyParams (https://github.com/mpociot/laravel-apidoc-generator/pull/597)
 
+### Modified
+- Made ResponseCalls strategy only execute if no successful responses exist. (https://github.com/mpociot/laravel-apidoc-generator/pull/605)
+- Hide null responses in examples. (https://github.com/mpociot/laravel-apidoc-generator/pull/605)
+- Made `responses` stage additive (https://github.com/mpociot/laravel-apidoc-generator/pull/605)
+- Renamed `query` and `body` in `response_calls` config to `queryParams` and `bodyParams` (https://github.com/mpociot/laravel-apidoc-generator/pull/603)
+
+### Removed
+- Removed `apply.response_calls.headers` in favour of `apply.headers` (https://github.com/mpociot/laravel-apidoc-generator/pull/603)
+- Removed bindings in response_calls (https://github.com/mpociot/laravel-apidoc-generator/pull/599)
+
 ## [3.17.1] - Thursday, 12 September 2019
 ### Fixed
 - ResponseCalls: Call Lumen application correctly since it does not use HttpKernel (https://github.com/mpociot/laravel-apidoc-generator/pull/585)

config/apidoc.php

@@ -1,12 +1,13 @@
 <?php
 
 return [
-
     /*
-     * The output path for the generated documentation.
-     * This path should be relative to the root of your application.
+     * The type of documentation output to generate.
+     * - "static" will generate a static HTMl page in the /public/docs folder,
+     * - "laravel" will generate the documentation as a Blade view,
+     * so you can add routing and authentication.
      */
-    'output' => 'public/docs',
+    'type' => 'static',
 
     /*
      * The router to be used (Laravel or Dingo).
@@ -21,6 +22,9 @@
 
     /*
      * Generate a Postman collection in addition to HTML docs.
+     * For 'static' docs, the collection will be generated to public/docs/collection.json.
+     * For 'laravel' docs, it will be generated to storage/app/apidoc/collection.json.
+     * The `ApiDoc::routes()` helper will add routes for both the HTML and the Postman collection.
      */
     'postman' => [
         /*
@@ -160,23 +164,23 @@
 
     'strategies' => [
         'metadata' => [
-            \Mpociot\ApiDoc\Strategies\Metadata\GetFromDocBlocks::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\Metadata\GetFromDocBlocks::class,
         ],
         'urlParameters' => [
-            \Mpociot\ApiDoc\Strategies\UrlParameters\GetFromUrlParamTag::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\UrlParameters\GetFromUrlParamTag::class,
         ],
         'queryParameters' => [
-            \Mpociot\ApiDoc\Strategies\QueryParameters\GetFromQueryParamTag::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\QueryParameters\GetFromQueryParamTag::class,
         ],
         'bodyParameters' => [
-            \Mpociot\ApiDoc\Strategies\BodyParameters\GetFromBodyParamTag::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\BodyParameters\GetFromBodyParamTag::class,
         ],
         'responses' => [
-            \Mpociot\ApiDoc\Strategies\Responses\UseResponseTag::class,
-            \Mpociot\ApiDoc\Strategies\Responses\UseResponseFileTag::class,
-            \Mpociot\ApiDoc\Strategies\Responses\UseApiResourceTags::class,
-            \Mpociot\ApiDoc\Strategies\Responses\UseTransformerTags::class,
-            \Mpociot\ApiDoc\Strategies\Responses\ResponseCalls::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseResponseTag::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseResponseFileTag::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseApiResourceTags::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseTransformerTags::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\Responses\ResponseCalls::class,
         ],
     ],
 

docs/config.md

@@ -2,8 +2,19 @@
 
 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.html#installation).
 
-## `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**
+## `type`
+This is the type of documentation output to generate.
+- `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.
+- `laravel` will generate the documentation as a Blade view within the `resources/views/apidoc` folder, so you can add routing and authentication.
+
+If you're using `laravel` type, you can call `\Mpociot\ApiDoc\ApiDoc::routes()` from your routes file (usually `routes/web.php`). This method will create a `/doc` route for your documentation, along with a `/doc.json` variant that will return the Postman collection, if you have that enabled. This method returns the route, so you can call additional methods to customise it (by adding middleware, for instance). You can also pass in the path you'd like to use instead.
+
+```php
+\Mpociot\ApiDoc\ApiDoc::routes("/apidoc")->middleware("auth.basic");
+```
+> 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.
+
+You may, of course, set up your own routing instead of using the `routes()` helper.
 
 ## `router`
 The router to use when processing your routes (can be Laravel or Dingo. Defaults to **Laravel**)
@@ -13,6 +24,8 @@ The base URL to be used in examples and the Postman collection. By default, this
 
 ## `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.
+- 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.
+- 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..
 
 ### `enabled`
 Whether or not to generate a Postman API collection. Default: **true**

docs/migrating.md

@@ -0,0 +1,2 @@
+# Migrating
+Rename your old config file. Publish the config file

docs/plugins.md

@@ -16,7 +16,7 @@ There are a number of strategies inccluded with the package, so you don't have t
 > 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.
 
 ## Strategies
-To create a strategy, create a class that extends `\Mpociot\ApiDoc\Strategies\Strategy`.
+To create a strategy, create a class that extends `\Mpociot\ApiDoc\Extracting\Strategies\Strategy`.
 
 The `__invoke` method of the strategy is where you perform your actions and return data. It receives the following arguments:
 - the route (instance of `\Illuminate\Routing\Route`)
@@ -31,7 +31,7 @@ The `__invoke` method of the strategy is where you perform your actions and retu
 <?php
 
 use Illuminate\Routing\Route;
-use Mpociot\ApiDoc\Strategies\Strategy;
+use Mpociot\ApiDoc\Extracting\Strategies\Strategy;
 
 class AddOrganizationIdBodyParameter extends Strategy
 {
@@ -55,23 +55,23 @@ The last thing to do is to register the strategy. Strategies are registered in a
 ...
     'strategies' => [
         'metadata' => [
-            \Mpociot\ApiDoc\Strategies\Metadata\GetFromDocBlocks::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\Metadata\GetFromDocBlocks::class,
         ],
         'urlParameters' => [
-            \Mpociot\ApiDoc\Strategies\UrlParameters\GetFromUrlParamTag::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\UrlParameters\GetFromUrlParamTag::class,
         ],
         'queryParameters' => [
-            \Mpociot\ApiDoc\Strategies\QueryParameters\GetFromQueryParamTag::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\QueryParameters\GetFromQueryParamTag::class,
         ],
         'bodyParameters' => [
-            \Mpociot\ApiDoc\Strategies\BodyParameters\GetFromBodyParamTag::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\BodyParameters\GetFromBodyParamTag::class,
         ],
         'responses' => [
-            \Mpociot\ApiDoc\Strategies\Responses\UseResponseTag::class,
-            \Mpociot\ApiDoc\Strategies\Responses\UseResponseFileTag::class,
-            \Mpociot\ApiDoc\Strategies\Responses\UseApiResourceTags::class,
-            \Mpociot\ApiDoc\Strategies\Responses\UseTransformerTags::class,
-            \Mpociot\ApiDoc\Strategies\Responses\ResponseCalls::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseResponseTag::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseResponseFileTag::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseApiResourceTags::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseTransformerTags::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\Responses\ResponseCalls::class,
         ],
     ],
 ...
@@ -82,7 +82,7 @@ You can add, replace or remove strategies from here. In our case, we're adding o
 ```php
 
         'bodyParameters' => [
-            \Mpociot\ApiDoc\Strategies\BodyParameters\GetFromBodyParamTag::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\BodyParameters\GetFromBodyParamTag::class,
             AddOrganizationIdBodyParameter::class,
         ],
 ```
@@ -124,9 +124,9 @@ You are also provided with the instance pproperty `stage`, which is set to the n
 ## Utilities
 You have access to a number of tools when developing strategies. They include:
 
-- The `RouteDocBlocker` class (in the `\Mpociot\ApiDoc\Tools` 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`.
+- 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`.
 
-- The `ParamsHelper` trait (in the `\Mpociot\ApiDoc\Tools` 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.
+- 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.
 
 ## API
 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.

src/ApiDoc.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Mpociot\ApiDoc;
+
+use Illuminate\Support\Facades\Route;
+use Illuminate\Support\Facades\Storage;
+
+class ApiDoc
+{
+    public static function routes($path = '/doc')
+    {
+        return Route::get("$path{format?}", function (?string $format = null) {
+            if ($format == '.json') {
+                return response(
+                    Storage::disk('local')->get('apidoc/collection.json'),
+                    200,
+                    ['Content-type' => 'application/json']
+
+                );
+            }
+
+            return view('apidoc.index');
+        })->name('apidoc');
+    }
+}