Update doc

Author: shalvah

README.md

@@ -1,4 +1,8 @@
-## Scribe ✍
+<h1 align="center">Scribe</h1>
+
+<p align="center">
+  <img src="logo-scribe.png"><br>
+</p>
 
 Generate API documentation for humans from your Laravel codebase. [Here's what the output looks like](https://shalvah.me/TheCensorshipAPI/).
 

config/scribe.php

@@ -54,7 +54,7 @@
          * The value of the parameter. This will NOT be part of the generated documentation.
          * Use it to easily auth response calls by this package. Otherwise, we'll use a random value.
          */
-        'use_value' => env('SCRIBE_API_KEY'),
+        'use_value' => env('SCRIBE_AUTH_KEY'),
 
         /*
          * Any extra info for your users. For instance, you can describe where to find (or generate) their auth credentials.
@@ -88,10 +88,16 @@
 
     /*
      * The base URL to be used in examples and the Postman collection.
-     * By default, this will be the value of config('app.url').
+     * If this is null, Scribe will use the value of config('app.url').
      */
     'base_url' => null,
 
+    /*
+     * 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').
+     */
+    'title' => null,
+
     /*
      * Generate a Postman collection in addition to HTML docs.
      * For 'static' docs, the collection will be generated to public/docs/collection.json.
@@ -104,11 +110,6 @@
          */
         'enabled' => true,
 
-        /*
-         * The name for the exported Postman collection. Default: config('app.name')." API"
-         */
-        'name' => null,
-
         /*
          * The description for the exported Postman collection.
          */

docs/config.md

@@ -1,4 +1,5 @@
 # Configuration
+[IN PROGRESS]
 
 Before you can generate your documentation, you'll need to configure a few things in your `config/scribe.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).
 
@@ -75,9 +76,7 @@ If you are using a custom serializer with league/fractal,  you can specify it he
 Leave this as null to use no serializer or return a simple JSON.
 
 ## `routes`
-The `routes` section is an array of items, describing what routes in your application that should have documentation generated for them. Each item in the array contains rules about what routes belong in that group, and what rules to apply to them. This allows you to apply different settings to different routes.
-
-> Note: This package does not work with Closure-based routes. If you want your route to be captured by this package, you need a controller.
+The `routes` section is an array of items, describing what routes in your application that should be included in the generated documentation. Each item in the array contains rules about what routes belong in that group, and what rules to apply to them. This allows you to apply different settings to different routes.
 
 Each item in the `routes` array (a route group) has keys which are explained below. We'll use this sample route definition for a Laravel app to demonstrate them:
 

docs/documenting-api-information.md

@@ -0,0 +1,67 @@
+# Adding general information about your API
+
+## Authentication information
+You can add authentication information for your API using the `auth` section in `scribe.php`. Scribe will use this in three places:
+- Generating an "Authentication" section in your docs
+- Adding authentication parameters o your rxample requests (for endpoints marked as `authenticated`)
+- Setting authentication information for response calls.
+
+Here's how you'd configure auth with a query parameter named `apiKey`:
+
+```php
+    'auth' => [
+        'enabled' => true,
+        'in' => 'query',
+        'name' => 'apiKey',
+        'use_value' => env('SCRIBE_API_KEY'),
+        'extra_info' => 'You can retrieve your key by going to settings and clicking <b>Generate API key</b>.',
+    ],
+```
+
+If `apiKey` were to be a body parameter, the config would be same. Just set `in` to `'body'`.
+
+Here's an example with a bearer token (also applies to basic auth, if you change `in` to `'basic'`):
+
+
+```php
+    'auth' => [
+        'enabled' => true,
+        'in' => 'bearer',
+        'name' => 'hahaha', // <--- This value is ignored for bearer and basic auth
+        'use_value' => env('SCRIBE_AUTH_KEY'),
+        'extra_info' => 'You can retrieve your token by visiting your dashboard and clicking <b>Generate API token</b>.',
+    ],
+```
+
+And here's an example with a custom header:
+
+
+```php
+    'auth' => [
+        'enabled' => true,
+        'in' => 'header',
+        'name' => 'Api-Key', // <--- The name of the header
+        'use_value' => env('SCRIBE_AUTH_KEY'),
+        'extra_info' => 'You can retrieve your token by visiting your dashboard and clicking <b>Generate API token</b>.',
+    ],
+```
+
+You can set whatever you want as the `extra_info`. A good idea would be to tell your users where to get their auth key. 
+
+The `use_value` field is only used by Scribe for response calls. It won't be included in the generated output or examples.
+
+For more information, see the [reference documentation on the auth section](config.html#auth).
+
+
+## Introductory text
+The `intro_text` key in `scribe.php` is where you can set the text shown to readers in the "Introduction" section. If your text is too long to be put in a config file, you can create a `prepend.md` containing the intro text and put it in the `resources/docs` folder.
+
+## Title
+You can set the HTML <title> for the generated documentation, and the name of the generated Postman collection by setting the `title` key in `scribe.php`. If you leave it as null, Scribe will infer it from the value of `config('app.name')`.
+
+## Logo
+Maybe you've got a pretty logo for your API or company, and you'd like to display that on your documentation page. No worries! To add a logo, set the `logo` key in `scribe.php` to the path of the logo. Here are your options:
+
+- To point to an image on an external public URL, set `logo` to that URL.
+- To point to an image in your codebase, set `logo` to the `public_path()` of the image, if you're using `laravel` type docs. If you're using `static` type, pass in the relative path to the image from the `public/docs` directory. For example, if your logo is in public/images, use '../img/logo.png' for `static` type and 'img/logo.png' for `laravel` type.
+- To disable the logo, set `logo` to false.

docs/documenting-endpoint-body-parameters.md

@@ -0,0 +1,103 @@
+# Documenting parameters for an endpoint
+[IN PROGRESS]
+
+## Specifying request parameters
+To specify a list of valid parameters your API route accepts, use the `@urlParam`, `@bodyParam` and `@queryParam` annotations.
+- The `@urlParam` annotation is used for describing parameters in your URl. For instance, in a Laravel route with this URL: "/post/{id}/{lang?}", you would use this annotation to describe the `id` and `lang` parameters. It takes the name of the parameter, an optional "required" label, and then its description.
+- The `@queryParam` annotation takes the name of the parameter, an optional "required" label, and then its description.
+- The `@bodyParam` annotation takes the name of the parameter, its type, an optional "required" label, and then its description. 
+
+Examples:
+
+```php
+/**
+ * @urlParam id required The ID of the post.
+ * @urlParam lang The language.
+ * @bodyParam user_id int required The id of the user. Example: 9
+ * @bodyParam room_id string The id of the room.
+ * @bodyParam forever boolean Whether to ban the user forever. Example: false
+ * @bodyParam another_one number Just need something here.
+ * @bodyParam yet_another_param object required Some object params.
+ * @bodyParam yet_another_param.name string required Subkey in the object param.
+ * @bodyParam even_more_param array Some array params.
+ * @bodyParam even_more_param.* float Subkey in the array param.
+ * @bodyParam book.name string
+ * @bodyParam book.author_id integer
+ * @bodyParam book[pages_count] integer
+ * @bodyParam ids.* integer
+ * @bodyParam users.*.first_name string The first name of the user. Example: John
+ * @bodyParam users.*.last_name string The last name of the user. Example: Doe
+ */
+public function createPost()
+{
+    // ...
+}
+
+/**
+ * @queryParam sort Field to sort by
+ * @queryParam page The page number to return
+ * @queryParam fields required The fields to include
+ */
+public function listPosts()
+{
+    // ...
+}
+```
+
+They will be included in the generated documentation text and example requests.
+
+**Result:**
+
+![](./../body_params_1.png)
+
+![](./../body_params_2.png)
+
+### Example parameters
+For each parameter in your request, this package will generate a random value to be used in the example requests. If you'd like to specify an example value, you can do so by adding `Example: your-example` to the end of your description. For instance:
+
+```php
+    /**
+     * @queryParam location_id required The id of the location.
+     * @queryParam user_id required The id of the user. Example: me
+     * @queryParam page required The page number. Example: 4
+     * @bodyParam user_id int required The id of the user. Example: 9
+     * @bodyParam room_id string The id of the room.
+     * @bodyParam forever boolean Whether to ban the user forever. Example: false
+     */
+```
+
+You can also exclude a particular parameter from the generated examples (for all languages) by annotating it with `No-example`. For instance:
+```php
+    /**
+    * @queryParam location_id required The id of the location. Example: 1
+    * @queryParam user_id required The id of the user. No-example
+    * @queryParam page required The page number. Example: 4
+    */
+```
+Outputs: 
+```bash
+curl -X GET -G "https://example.com/api?location_id=1&page=4"
+```
+
+Note: You can also add the `@queryParam` and `@bodyParam` annotations to a `\Illuminate\Foundation\Http\FormRequest` subclass instead, if you are using one in your controller method
+
+```php
+/**
+ * @queryParam user_id required The id of the user. Example: me
+ * @bodyParam title string required The title of the post.
+ * @bodyParam body string required The content of the post.
+ * @bodyParam type string The type of post to create. Defaults to 'textophonious'.
+ * @bodyParam author_id int the ID of the author. Example: 2
+ * @bodyParam thumbnail image This is required if the post type is 'imagelicious'.
+ */
+class MyRequest extends \Illuminate\Foundation\Http\FormRequest
+{
+
+}
+
+// in your controller...
+public function createPost(MyRequest $request)
+{
+    // ...
+}
+```

docs/documenting-endpoint-headers.md

@@ -0,0 +1,19 @@
+# Documenting headers for endpoints
+
+To specify headers to be added to your endpoints, use the `apply.headers` section of the route group in `scribe.php`. For instance, if you have this config:
+
+```php
+  'routes' => [
+    [
+      'match' => [
+        'domains' => ['*'],
+        'prefixes' => ['v2/'],
+      ],
+      'apply' => [
+        'headers' => [ 'Api-Version' => 'v2']
+      ]
+    ]
+  ]
+```
+
+All endpoints that start with `v2/` will have the header `Api-Version: v2` included in their example requests and response calls.

docs/documenting-endpoint-metadata.md

@@ -0,0 +1,82 @@
+# Specifying metadata about an endpoint
+
+## Endpoint title and description
+To set an endpoint's title and description, just write in the method's docblock. The first paragraph will be used as the title, the rest as the description. Custom formatting (such as `<aside>` tags) is also supported (see the [Pastel docs](http://github.com/knuckleswtf/pastel))
+
+For instance, this:
+
+```php
+    /**
+     * Add a word to the list.
+     * This endpoint allows you to add a word to the list. It's a really useful endpoint,
+     * and you should play around with it for a bit.
+     * <aside class="notice">We mean it; you really should.😕</aside>
+     */
+    public function store(Request $request)
+    {
+        //...
+    }
+```
+
+becomes:
+
+![](images/endpoint-title-description.png)
+
+## Grouping endpoints
+All endpoints are grouped for easy navigation.
+
+To add all endpoints in a controller to a group, use `@group` in the controller docblock, followed by the group's title. You can also add a description below the group.
+
+You can also specify an `@group` on a single method to override the group defined at the controller level.
+
+```php
+/**
+ * @group User management
+ *
+ * APIs for managing users
+ */
+class UserController extends Controller
+{
+
+	/**
+	 * Create a user.
+	 */
+	 public function createUser()
+	 {
+
+	 }
+	 
+	/**
+     * Change a user's password.
+     * 
+	 * @group Account management
+	 */
+	 public function changePassword()
+	 {
+
+	 }
+}
+``` 
+
+![Doc block result](images/endpoint-groups.png)
+
+Grouping endpoints is optional. Any endpoints not in a group will be placed in a default group, "Endpoints".
+
+## Indicating authentication status
+You can use the `@authenticated` annotation on a method to indicate if the endpoint is authenticated. A "Requires authentication" badge will be added to that route in the generated documentation. 
+
+If all the routes in a controller are authenticated, you can specify `@authenticated` in the controller doc block instead. 
+
+```php
+    /**
+     * Create a user
+     * This endpoint lets you create a user.
+     * @authenticated
+     *
+     */
+     public function create()
+     {    
+     }
+```
+
+![](images/endpoint-auth.png)