Update docs

config/scribe.php

@@ -41,12 +41,12 @@ return [
         'middleware' => [],
     ],
 
-    'output' => [
-        /**
-         * Add a Try It Out button to your endpoints so consumers can test endpoints right from their browser.
-         */
-        'interactive' => true,
-    ],
+    /**
+     * Add a Try It Out button to your endpoints so consumers can test endpoints right from their browser.
+     * Don't forget to enable CORS headers for your endpoints.
+     */
+    'interactive' => true,
+
     /*
      * How is your API authenticated? This information will be used in the displayed docs, generated examples and response calls.
      */

docs/config.md

@@ -41,6 +41,13 @@ The HTML `<title>` for the generated documentation, and the name of the generate
 ### `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.
 
+### `interactive`
+Set this to `true` if you'd like Scribe to add a "Try It Out" button to your endpoints so users can test them from their browser. Default: `true`.
+
+```eval_rst
+..Important:: For "Try It Out" to work, you'll need to make sure CORS is enabled on your endpoints. An easy package for this is `fruitcake/laravel-cors <https://github.com/fruitcake/laravel-cors>`_.
+```
+
 ### `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`.
 

docs/documenting/documenting-endpoint-body-parameters.md

@@ -11,9 +11,11 @@ The `@bodyParam` annotation takes the name of the parameter, its type, an option
 - `integer`
 - `number`
 - `boolean`
-- `array`, `object` (see [Handling array and object parameters](#handling-array-and-object-parameters) below)
+- `object` (see [Handling array and object parameters](#handling-array-and-object-parameters) below)
 - `file` (see [Documenting File Uploads](#documenting-file-uploads) below)
 
+You can append `[]` at the end of a type any number of times to indicate an array field (`integer[]` = array of integers).
+
 By default, Scribe will generate a random value for each parameter, to be used in the example requests and response calls. If you'd like to use a specific example value, you can do so by adding `Example: your-example-here` to the end of your description.
 
 ```eval_rst
@@ -60,23 +62,21 @@ public function createPost(CreatePostRequest $request)
 ```
 
 ### Handling array and object parameters
-Sometimes you have body parameters that are arrays or objects. To handle them in `@bodyparam`, Scribe follows Laravel's convention:
-- For arrays: use `<name>.*`
-- For objects: use `<name>.<key>`.
-
-This means that, for an array of objects, you'd use `<name>.*.<key>`.
+Sometimes you have body parameters that are arrays or objects. To handle them in `@bodyparam`, Scribe follows this convention:
 
-You can also add a "parent" description if you like, by using `@bodyParam` with the type as "object" or "array".
+- To denote an array `cars` of elements of type `integer`: `@bodyParam cars integer[]`
+- To denote an object `cars` with a field `name` of type `string`: `@bodyParam cars object` + `@bodyParam cars.name string`.
+- To denote an array of objects `cars` with each item having field `name`: `@bodyParam cars object[]` + `@bodyParam cars[].name string`.
 
 ```php
 /**
  * @bodyParam user object required The user details
  * @bodyParam user.name string required The user's name
- * @bodyParam user.age string required The user's age
- * @bodyParam friend_ids array List of the user's friends.
- * @bodyParam friend_ids.* int User's friends.
- * @bodyParam cars.*.year string The year the car was made. Example: 1997
- * @bodyParam cars.*.make string The make of the car. Example: Toyota
+ * @bodyParam user.age string required The user's age 
+ * @bodyParam friend_ids int[] List of the user's friends.
+ * @bodyParam cars object[] List of cars
+ * @bodyParam cars[].year string The year the car was made. Example: 1997
+ * @bodyParam cars[].make string The make of the car. Example: Toyota
  */
 ```
 

docs/documenting/documenting-endpoint-query-parameters.md

@@ -3,13 +3,15 @@
 ## Specifying query parameters
 To describe query parameters for your endpoint, use the `@queryParam` annotation on the method handling it.
 
-The `@queryParam` annotation takes the name of the parameter, an optional "required" label, and a description.
+The `@queryParam` annotation takes the name of the parameter, an optional type, an optional "required" label, and a description.
+
+If you don't specify a type, Scribe will assume it's `string`. See [the documentation on body parameters](./documenting/documenting-endpoint-body-parameters.html) for a list of valid types.
 
 Here's an example:
 
 ```php
 /**
- * @queryParam sort Field to sort by. Defaults to 'id'.
+ * @queryParam sort string Field to sort by. Defaults to 'id'.
  * @queryParam fields required Comma-separated fields to include in the response
  * @queryParam filters[published_at] Filter by date published.
  * @queryParam filters[title] Filter by title.
@@ -72,11 +74,13 @@ To describe parameters in the URL, use the `@urlParam` annotation. For instance,
 Route::get("/post/{id}/{lang?}");
 ```
 
-you can use this annotation to describe the `id` and `lang` parameters as shown below. The annotation takes the name of the parameter, an optional "required" label, and then its description. Like with `@queryParams`, a random value will be generated, but you can specify the value to be used in examples and response calls using the `Example: ` syntax.
+you can use this annotation to describe the `id` and `lang` parameters as shown below. The annotation takes the name of the parameter, an optional type, an optional "required" label, and then its description. Like with `@queryParams`, a random value will be generated, but you can specify the value to be used in examples and response calls using the `Example: ` syntax.
+
+If you don't specify a type, Scribe will assume it's `string`. Valid types are `string`, `integer`, and `number`.
 
 ```php
 /**
- * @urlParam id required The ID of the post.
+ * @urlParam id integer required The ID of the post.
  * @urlParam lang The language. Example: en
  */
 public function getPost()

docs/generating-documentation.md

@@ -16,6 +16,11 @@ Accessing your generated docs depends on the `type` you specified in `scribe.php
 - If you're using `static` type, find the `docs/index.html` file in your `public/` folder and open that in your browser.
 - If you're using `laravel` type, start your app (`php artisan serve`), then visit `/docs`.
 
+## Configuring interactive documentation
+When `interactive` is set to `true` (which is also the default value) in your config, Scribe will add a "Try It Out" button to your endpoints so users can test them from their browser.
+
+For this to work, though, you'll need to make sure CORS is enabled. An easy package for this is [`fruitcake/laravel-cors`](https://github.com/fruitcake/laravel-cors).
+
 ## Postman collection generation
 By default, a Postman collection file which you can import into API clients like Postman or Insomnia is generated alongside your docs. You can view it by visiting `public/docs/collection.json` for `static` type, and `<your-app>/docs.json` for `laravel` type. This link will also be added to the sidebar of your docs.
 

docs/migrating-v2.md

@@ -1,19 +1,42 @@
-Scribe 2 comes with a bunch of changes focused on making the documentation process easier and the output better. Some of these changes were introduced in recent minor versions, so we'll highlight them here in case you missed them.
+# Scribe 2: what's new, and how to migrate
 
-- "Try It Out" button gives you free interactive documentation 
+Scribe 2 comes with a bunch of changes focused on making the documentation process easier and the output nicer. There aren't many "shiny" changes, mostly improvements to what works. For the most part, you won't need to do much work. We've marked required changes in the list below with a "Migration Required" label.
 
-## The new `description` field replaces `postman.description`
-The `description` field, where you can add a description of your API. This field will be used in the following ways:
-- as the `info.description` field in the Postman collection
-- as the `info.description` field in the OpenAPI spec
-- as the first paragraph under the "Introduction" section on the webpage, before the `intro_text`
+This is also a release announcement for Scribe for JS! [Version 1 has now been released]()!🎉 
 
-Since we've added this field, we've removed the Postman-specific `postman.description`.
+# Changes in the output 
 
-## `postman.auth` has been removed in favour of `postman.overrides`
+## "Try It Out": interactive documentation with (probably) zero config ⚡💥
+Big news: Your docs will now include a "Try t Out" button that allows users to test out an endpoint, right from their browser.
+
+![](./images/tryitout-button.png)
+
+![](./images/tryitout-button-2.png)
+
+To enable this, set `interactive` to true. Don't forget to enable CORS headers in your API! Here's the [full doc](./generating-documentation.html#configuring-interactive-documentation).
+
+## Object fields are now represented better in the docs
+Object fields are now wrapped in a `<details>` element, so you can expand the dropdown to see fields within an object.
+
+![](./images/object-fields.png)
+
+![](./images/object-fields-expanded.png)
+
+
+# Changes to the config file
+   
+## `auth.default`: Specify the default auth status of endpoints
+Previously, if you had an API with all endpoints authenticated, you had to set `auth.enabled` to true, AND use `@authenticated` on every endpoint. Pain in the ass. Now you can mark all endpoints as authenticated, by setting `auth.default` to true (don't forget to set `uaht.enabled` to true as well). You can also remove auth from specific endpoints with `@unauthenticated`.
+   
+## [Migration Required] `description` replaces `postman.description`
+In 1.6.0, we added a `description` config item, where you can add a description of your API. This field is used as the `info.description` field in the Postman collection and OpenAPI spec, and as the first paragraph under the "Introduction" section on the docs webpage, before the `intro_text`. We've now removed `postman.description`.
+
+**How to migrate**: Move the contents of your `postman.description` to `description`.
+
+## [Migration Required] `postman.auth` has been removed in favour of `postman.overrides`
 We've removed `postman.auth`. It didn't make sense to have two ways of setting Postman-specific auth information (`postman.auth` and `postman.overrides`).
 
-How to migrate: If you need to set Postman-specific auth now, use an `auth` key in `postman.overrides`:
+**How to migrate**: If you need to set Postman-specific auth now, use an `auth` key in `postman.overrides`:
 
 ```php
 'postman' => [
@@ -23,53 +46,72 @@ How to migrate: If you need to set Postman-specific auth now, use an `auth` key
 ]
 ```
 
+Note that Scribe now automatically populates auth info in the collection (based on your config file), so you might not even need this.
 
-## Types are now supported for URL and query parameters
-Previously, you couldn't specify types for URL and query parameters. The idea was that it didn't make sense, since they're all passed as strings in the URL anyway. But we've changed that. The thinking now is that these types can pass semantic information to your API consumers—even though they're strings in the URL, they have actual significance outside of that. You can now pass types for URL and query parameters.
+# Changes in extracting docs
+## [Migration Required] New syntax for array and object parameters
+The old dot notation syntax was based on Laravel's validation syntax. However, it had a few limitations in our case. It was based on PHP semantics (eg JSON objects are PHP arrays), which meant it didn't fit well for documenting types. It was also unclear whether you needed or were able to document parent fields as well as individual fields.
 
-How to migrate:
-If you don't want to use this, no problem! All URL and query parameters will remain `string` by default. If you'd like to add types, just specify a type with @urlParam and @queryParam like you'd  do with @bodyParam (after the parameter name).
+So we've switched to a new syntax. It uses some elements of the old, but is clearer and easier to work with. It also makes the output more intuitive to an end user.
 
-If you have custom strategies, you should update them
+Here's a comparison of the two, using `@bodyParam` as an example:
 
-## New syntax for array and object parameters
-The old dot notation syntax was based on Laravel's validation syntax. However, it had a few limitations in our case. It wasn't well-thought out, and was based on PHP semantics rather than JSON, which meant it didn't fit really well for documenting types. The new syntax uses some elements of the old.
+- To denote an array `cars` of elements of type `integer`.
+  
+  **Old syntax**: `@bodyParam cars.* integer` + `@bodyParam cars array` (optional).
+  
+  **New syntax**: `@bodyParam cars integer[]`
+- To denote an object `cars` with a field `name` of type `string`. No changes!
+  
+  **Syntax**: `@bodyParam cars object` + `@bodyParam cars.name string`.
+- To denote an array of objects `cars` with each item having field `name`.
+  
+  **Old syntax**: `@bodyParam cars.* object` + `@bodyParam cars.*.name string`.
+  
+  **New syntax**: `@bodyParam cars object[]` + `@bodyParam cars[].name string`.
 
-How to migrate: 
+**How to migrate:**
+You'll need to run a search through all your docblocks:
+- Replace `.*.` with '[].'
+- Make sure `.*` fields and fields with `array` type are replaced with the correct `x[]` type field. 
+- Ensure there's a parent object for object fields. For instance, you can't have a `cars.name string` field without a `cars object` field.
 
-Description | Old | New
------------|------|---------
-To denote an array `cars` of elements of type x | cars array, cars.* x | cars x[]
-To denote an object `cars` | cars object | cars object
-To denote an object `cars` with fields | cars object, cars.name string | cars object, cars.name string
-To denote an array of objects `cars` with fields | cars.* object, cars.*.name string | cars object[], cars[].name string
+If you're using FormRequests, you don't need to worry about those. Scribe can handle those.
 
-Replace `.*.` in docblocks with '[].'
-Replace `.*` in docblocks with `[]` appended to the type name 
-Ensure there's parent object for object fields
+## Types are now supported for URL and query parameters
+Previously, you couldn't specify types for URL and query parameters. The idea was that it didn't make sense, since they're all passed as strings in the URL anyway. But we've changed that. The thinking now is that these types can hold semantic information, which matters to your API consumers—even though they're strings in the URL, they have actual significance outside of that. You can now pass types for URL and query parameters.
 
-## add_routes: Postman collection route renamed
-When you use `laravel` type docs and have `add_routes` set to `true`, you'll have three routes added to your Laravel app: one for the webpage, one for the Postman collection and one for the OpenAPI spec. The route for the Postman collection was previously named `scribe.json`, but has now been renamed to `scribe.postman`, to bring it in line with the OpenAPI route, which is named `scribe.openapi`.
+**How to migrate**:
+- In your annotations: If you don't want to use this, no problem! All URL and query parameters will remain `string` by default. If you'd like to add types, just specify a type with `@urlParam` and `@queryParam` like you'd do with `@bodyParam` (after the parameter name).
+- In custom strategies: Update any custom strategies you've written so they return a `type` field for each URL and query parameter
 
-## Switch Postman base URL to use variables
-Postman collection base URL now uses a variale, so you can change the base URL for all endpoints in your collection easier.
+# Other changes
+### `@responseFile` supports other directories
+You can now specify a file located anywhere on your machine with `@responseFile`. The file path can either be an absolute path, a path relative to your project root, or a path relative to the Laravel storage directory.
 
-## Represent object/array fields better in docs
+### `add_routes`: Postman collection route renamed
+When you use `laravel` type docs and have `add_routes` set to `true`, you get three routes added to your Laravel app: one for the webpage, one for the Postman collection and one for the OpenAPI spec. The route for the Postman collection was previously named `scribe.json`, but has now been renamed to `scribe.postman`, to bring it in line with the OpenAPI route, which is named `scribe.openapi`.
 
-## New config file structure
+### Postman base URL now uses Postman variables
+Postman collection base URL now uses a `{{baseUrl}}` variable, so you can change the base URL for all endpoints in your collection easier.
 
-- title
-- description
-- output => 
-    'webpage' => type, intro_text, output_path, logo, etc
-    'postman' =>
-    'openapi' => 
-   ]
-   
-   
-   
-   ## `auth.default` key added
-   
-   # API: include 'name' in parameter details
-   
-   ## @responseFile supports other directories
+### [Migration Required] Plugin API changes: include 'name' in parameter details
+This only applies if you have custom strategies. All strategies that return URL, query or body parameters or response fields must now include the name of the field as a `name` field in the returned array. This means that the parameter name is going to be mentioned twice in the result from the strategy:
+
+```php
+return [
+  'param1' => [ // <-- here
+    'name' => 'param1',  // <-- and here
+    'description' => '...'
+  ],
+  'param2' => [ // <-- here
+    'name' => 'param2',  // <-- and here
+    'description' => '...'
+  ],
+];
+```
+
+We know it's kinda silly 🙄, but it's actually a small optimisation that makes things easier in the long run.
+
+<hr>
+Thanks for using Scribe! We hope you have fun and write kickass API docs! And if you'd like to get better at API documentation, I recently launched a course you might want to check out: [apidocsfordevs.com](https://apidocsfordevs.com).

docs/plugins.md

@@ -214,12 +214,14 @@ Each strategy class must implement the `__invoke` method with the parameters as
 
 ```php
 [
+  'name' => 'Parameter name',
   'type' => 'valid type',
   'description' => 'An optional description.', 
   'required => true, // or false
   'value' => "An example value for the parameter",
 ];
 ```
+See [the documentation on body parameters](./documenting/documenting-endpoint-body-parameters.html) for a list of valid types.
 
 ```eval_rst
 .. Tip:: If you would like a parameter (body or query) to be included in the documentation but excluded from examples, set `required` to false and `value` property to `null`, like we did in our example above.
@@ -251,6 +253,7 @@ Each strategy class must implement the `__invoke` method with the parameters as
 
 ```
 [
+  'name' => '',
   'type' => '',
   'description' => '',
 ]