Merge branch 'master' into master

.travis.yml

@@ -36,4 +36,4 @@ install:
   - if [[ $SETUP = 'lint' ]]; then travis_retry composer update --prefer-dist --no-interaction --prefer-stable --no-suggest; composer lint -- --memory-limit 1G; fi
 
 script:
-  - if [[ $SETUP = 'lint' ]]; then exit 0; fi; composer test-ci;
+  - if [[ $SETUP = 'lint' ]]; then exit 0; fi; composer test-parallel-ci;

CHANGELOG.md

@@ -3,14 +3,19 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project aims to adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Unreleased
+## 1.6.0 (Tuesday, 8 September, 2020)
 ### Additions
+- New `description` field, where you can add a description of your API. This field will be used as the `info.description` field in the Postman collection and OpenAPI spec, and as the first paragraph under the "Introduction" section on the generated webpage, before the `intro_text`. (https://github.com/knuckleswtf/scribe/pull/90/commits/dc356f3f2b13732d567dbee88dad07fc0441f40e)
+- Postman collection `auth` information is now populated from Scribe's auth info. (https://github.com/knuckleswtf/scribe/pull/90/commits/33c00a7a0b915e9cbedccdb13d7cb4fcc3c76dc5)
 
-### Changes
+#### Changes
+- Postman collection schema version has been updated to 2.1.0. (https://github.com/knuckleswtf/scribe/pull/90/commits/cc7e4cbfae08999f555f7a105ab3c2993fdbb2c1)
+- The `float` type is now `number`: Previously, `float` was used in the generated webpage as the default type for non-integer numbers, in alignment with PHP's type system. We've changed this to `number`, to align with standards like OpenAPI and JSON types. You can still use `float` in your annotations, but it will be rendered as `number`. (https://github.com/knuckleswtf/scribe/pull/90/commits/66993d2d2c7a1a57806960dd4cc428068fb0f589)
+- [Internal] Reworked PostmanCollectionWriter API: The `PostmanCollectionWriter` has been reworked to be more in line with the `OpenAPISpecWriter`. See the class for details.
 
-### Fixes
-
-### Removals
+#### Deprecations
+- Deprecated `postman.auth` in favour of `postman.overrides`: It didn't make sense to have two ways of setting Postman-specific auth information (`postman.auth` and `postman.overrides`). Will be removed in v2.
+- Deprecated Postman-specific `postman.description` in favour of `description`. Will be removed in v2.
 
 ## 1.5.0 (Thursday, 3 September, 2020)
 ### Additions

composer.dingo.json

@@ -22,10 +22,10 @@
         "dingo/api": "^2.3",
         "erusev/parsedown": "^1.7.4",
         "fzaninotto/faker": "^1.9.1",
-        "illuminate/console": "^5.8|^6.0|^7.0|^8.0",
-        "illuminate/routing": "^5.8|^6.0|^7.0|^8.0",
-        "illuminate/support": "^5.8|^6.0|^7.0|^8.0",
-        "knuckleswtf/pastel": "^1.3.3",
+        "illuminate/console": "^5.8|^6.0|^7.0",
+        "illuminate/routing": "^5.8|^6.0|^7.0",
+        "illuminate/support": "^5.8|^6.0|^7.0",
+        "knuckleswtf/pastel": "^1.3.5",
         "league/flysystem": "^1.0",
         "mpociot/reflection-docblock": "^1.0.1",
         "nunomaduro/collision": "^3.0|^4.0|^5.0",
@@ -59,8 +59,8 @@
         "lint": "phpstan analyse -c ./phpstan.neon src",
         "test": "phpunit --stop-on-failure --group dingo",
         "test-ci": "phpunit --group dingo",
-        "test-parallel": "paratest -p3 --stop-on-failure --parallel-suite --group dingo tests",
-        "test-parallel-ci": "paratest -p3 --parallel-suite --group dingo tests"
+        "test-parallel": "paratest -p4 --stop-on-failure --parallel-suite --group dingo tests",
+        "test-parallel-ci": "paratest -p4 --parallel-suite --group dingo tests"
     },
     "extra": {
         "laravel": {

composer.json

@@ -21,10 +21,10 @@
     "ext-json": "*",
     "erusev/parsedown": "^1.7.4",
     "fzaninotto/faker": "^1.9.1",
-    "illuminate/console": "^5.8|^6.0|^7.0|^8.0",
-    "illuminate/routing": "^5.8|^6.0|^7.0|^8.0",
-    "illuminate/support": "^5.8|^6.0|^7.0|^8.0",
-    "knuckleswtf/pastel": "^1.3.3",
+    "illuminate/console": "^5.8|^6.0|^7.0",
+    "illuminate/routing": "^5.8|^6.0|^7.0",
+    "illuminate/support": "^5.8|^6.0|^7.0",
+    "knuckleswtf/pastel": "^1.3.5",
     "league/flysystem": "^1.0",
     "mpociot/reflection-docblock": "^1.0.1",
     "nunomaduro/collision": "^3.0|^4.0|^5.0",
@@ -59,8 +59,8 @@
     "lint": "phpstan analyse -c ./phpstan.neon src",
     "test": "phpunit --stop-on-failure --exclude-group dingo",
     "test-ci": "phpunit --exclude-group dingo",
-    "test-parallel": "paratest -p3 --stop-on-failure --parallel-suite --exclude-group dingo tests",
-    "test-parallel-ci": "paratest -p3 --parallel-suite --exclude-group dingo tests"
+    "test-parallel": "paratest -p4 --stop-on-failure --parallel-suite --exclude-group dingo tests",
+    "test-parallel-ci": "paratest -p4 --parallel-suite --exclude-group dingo tests"
   },
   "extra": {
     "laravel": {

config/scribe.php

@@ -82,7 +82,7 @@ return [
     ],
 
     /*
-     * Text to place in the "Introduction" section. Markdown and HTML are supported.
+     * Text to place in the "Introduction" section, right after the `description`. Markdown and HTML are supported.
      */
     'intro_text' => <<<INTRO
 Welcome to our API documentation!

docs/config.md

@@ -38,6 +38,9 @@ The text to place in the "Introduction" section. Markdown and HTML are supported
 ### `title`
 The HTML `<title>` for the generated documentation, and the name of the generated Postman collection. If this is `null`, Scribe will infer it from `config('app.name')`.
 
+### `description`
+A description for your API. This will be placed in the "Introduction" section, before the `intro_text`. It will also be used as the `info.description` field in the generated Postman collection and OpenAPI spec.
+
 ### `logo`
 Path to an image file to use as your logo in the generated docs. This will be used as the value of the src attribute for the `<img>` tag, so make sure it points to a public URL or path accessible from your web server. For best results, the image width should be 230px. Set this to `false` if you're not using a logo. Default: `false`.
 
@@ -83,6 +86,7 @@ The router to use when processing your routes. Can be `laravel` or `dingo`. Defa
 ### `auth`
 Authentication information about your API. This information will be used:
 - to derive the text in the "Authentication" section in the generated docs
+- to generate auth info in the Postman collection and OpenAPI spec
 - to add the auth headers/query parameters/body parameters to the docs and example requests
 - to set the auth headers/query parameters/body parameters for response calls
 

docs/plugins.md

@@ -209,13 +209,15 @@ Each strategy class must implement the `__invoke` method with the parameters as
 'authenticated' // boolean
 ```
 
-- In the `urlParameters`, `queryParameters`, and `bodyParameters` stages, you can return an array with arbitrary keys. These keys will be 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:
+- In the `urlParameters`, `queryParameters`, and `bodyParameters` stages, you can return an array with arbitrary keys. These keys will be 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 structure:
 
-```
-'type', // Only valid in bodyParameters
-'description', 
-'required', // boolean
-'value', // An example value for the parameter
+```php
+[
+  'type' => 'valid type',
+  'description' => 'An optional description.', 
+  'required => true, // or false
+  'value' => "An example value for the parameter",
+];
 ```
 
 ```eval_rst
@@ -244,9 +246,11 @@ Each strategy class must implement the `__invoke` method with the parameters as
 ```
 
 
-- In the `responseFields` stage, you can return an array with arbitrary keys. These keys will be the names of fields in your response. The value of each key should be an array with the following keys:
+- In the `responseFields` stage, you can return an array with arbitrary keys. These keys will be the names of fields in your response. The value of each key should be an array with the following structure:
 
 ```
-'type',
-'description',
+[
+  'type' => '',
+  'description' => '',
+]
 ```

phpunit.xml

@@ -3,7 +3,7 @@
          backupStaticAttributes="false"
          bootstrap="vendor/autoload.php"
          cacheResult="true"
-         colors="true"
+         colors="false"
          convertErrorsToExceptions="true"
          convertNoticesToExceptions="true"
          convertWarningsToExceptions="true"
@@ -25,11 +25,13 @@
             <file>tests/Unit/RouteMatcherDingoTest.php</file>
             <file>tests/Unit/RouteMatcherTest.php</file>
         </testsuite>
-        <testsuite name="Other Unit Tests">
-            <file>tests/Unit/PostmanCollectionWriterTest.php</file>
+        <testsuite name="Other Unit Tests 1">
             <file>tests/Unit/OpenAPISpecWriterTest.php</file>
             <file>tests/Unit/AnnotationParserTest.php</file>
         </testsuite>
+        <testsuite name="Other Unit Tests 2">
+            <file>tests/Unit/PostmanCollectionWriterTest.php</file>
+        </testsuite>
     </testsuites>
     <filter>
         <whitelist>