From 9c46db3e2b1b91836c3556b342871609d22f189b Mon Sep 17 00:00:00 2001 From: shalvah Date: Tue, 8 Sep 2020 13:09:33 +0100 Subject: [PATCH] Update docs --- config/scribe.php | 2 +- docs/config.md | 4 ++++ docs/plugins.md | 22 +++++++++++++--------- 3 files changed, 18 insertions(+), 10 deletions(-) diff --git a/config/scribe.php b/config/scribe.php index 2294bccb..5159d124 100644 --- 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' => <<` 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 `` 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 index 316d0fa7..4919c2d5 100644 --- 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' => '', +] ```