Update docs

knuckleswtf · Sep 8, 2020 · 9c46db3 · 9c46db3
1 parent 4d3648f
commit 9c46db3
Show file tree

Hide file tree

Showing 3 changed files with 18 additions and 10 deletions.
diff --git a/config/scribe.php b/config/scribe.php
@@ -82,7 +82,7 @@
     ],
 
     /*
-     * 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!

diff --git a/docs/config.md b/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
 

diff --git a/docs/plugins.md b/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' => '',
+]
 ```