Browse Source

Update docs

shalvah 6 years ago
parent
commit
1d4d154d36
4 changed files with 11 additions and 11 deletions
  1. 3 3
      docs/config.md
  2. 1 1
      docs/description.md
  3. 6 6
      docs/documenting.md
  4. 1 1
      docs/generating-documentation.md

+ 3 - 3
docs/config.md

@@ -1,6 +1,6 @@
 # Configuration
 
-Before you can generate your documentation, you'll need to configure a few things in your `config/apidoc.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.md#installation).
+Before you can generate your documentation, you'll need to configure a few things in your `config/apidoc.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).
 
 ## `output`
 This is the file path where the generated documentation will be written to. Note that the documentation is generated as static HTML and CSS assets, so the route is accessed directly, and not via the Laravel routing mechanism. This path should be relative to the root of your application. Default: **public/docs**
@@ -32,7 +32,7 @@ If you want to use this, please note that the image size must be 230 x 52.
 When [documenting your api](documenting.md), you use `@group` annotations to group API endpoints. Endpoints which do not have a ggroup annotation will be grouped under the `default_group`. Defaults to **"general"**.
 
 ##  `faker_seed`
-When generating example requests, this package uses fzanninoto/faker to generate random values. If you would like the package to generate the same example values for parameters on each run, set this to any number (eg. 1234). (Note: alternatively, you can set example values for parameters when [documenting them.](documenting.md#specifying-request-parameters))
+When generating example requests, this package uses fzanninoto/faker to generate random values. If you would like the package to generate the same example values for parameters on each run, set this to any number (eg. 1234). (Note: alternatively, you can set example values for parameters when [documenting them.](documenting.html#specifying-request-parameters))
        
 ## `fractal`
 This section only applies if you're using [Transformers]() for your API, and documenting responses with `@transformer` and `@transformerCollection`. Here, you configure how responses are transformed.
@@ -211,4 +211,4 @@ After defining the routes in `match` (and `include` or `exclude`), `apply` is wh
 Like we've demonstrated above, any headers you specify here will be added to the headers shown in the example requests in your documenation. Headers are specified as key => value strings.
 
 #### `response_calls`
-These are the settings that will be applied when making ["response calls"](documenting.md#generating-responses-automatically). See the linked section for details.
+These are the settings that will be applied when making ["response calls"](documenting.html#generating-responses-automatically). See the linked section for details.

+ 1 - 1
docs/description.md

@@ -6,4 +6,4 @@ After installing this package and runing the command `php artisan apidoc:generat
 - It looks through your [configuration file](config.md) to filter the routes to the ones you actually want to document. For each route, it retrieves the settings you want to apply to it, if any.
 - It processes each route. "Process" here involves using a number of strategies to extract the route's information: group, title, description, body parameters, query parameters, and a sample response, if possible.
 - After processing the routes, it generates a markdown file describing the routes from the parsed data and passes them to [Documentarian](https://github.com/mpociot/documentarian), which wraps them in a theme and converts them into HTML and CSS.
-- It generates a Postman API collection for your routes. ([This can be disabled.](config.md#postman))
+- It generates a Postman API collection for your routes. ([This can be disabled.](config.html#postman))

+ 6 - 6
docs/documenting.md

@@ -120,13 +120,13 @@ public function createPost(MyRequest $request)
 }
 ```
 
-### Indicating authentication status
+## 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.
 
-### Providing an example response
+## Providing an example response
 You can provide an example response for a route. This will be displayed in the examples section. There are several ways of doing this.
 
-#### @response
+### @response
 You can provide an example response for a route by using the `@response` annotation with valid JSON:
 
 ```php
@@ -161,7 +161,7 @@ public function show($id)
 }
 ```
 
-#### @transformer, @transformerCollection, and @transformerModel
+### @transformer, @transformerCollection, and @transformerModel
 You can define the transformer that is used for the result of the route using the `@transformer` tag (or `@transformerCollection` if the route returns a list). The package will attempt to generate an instance of the model to be transformed using the following steps, stopping at the first successful one:
 
 1. Check if there is a `@transformerModel` tag to define the model being transformed. If there is none, use the class of the first parameter to the transformer's `transform()` method.
@@ -208,7 +208,7 @@ For the first route above, this package will generate a set of two users then pa
 composer require league/fractal
 ```
 
-#### @responseFile
+### @responseFile
 
 For large response bodies, you may want to use a dump of an actual response. You can put this response in a file (as a JSON string) within your Laravel storage directory and link to it. For instance, we can put this response in a file named `users.get.json` in `storage/responses`:
 
@@ -241,7 +241,7 @@ public function getUser(int $id)
 }
 ```
 
-### Generating responses automatically
+## Generating responses automatically
 If you don't specify an example response using any of the above means, this package will attempt to get a sample response by making a request to the route (a "response call"). A few things to note about response calls:
 
 - Response calls are done within a database transaction and changes are rolled back afterwards.

+ 1 - 1
docs/generating-documentation.md

@@ -23,7 +23,7 @@ The base URL added to the Postman collection will be the value of the `url` key
 ## Manually modifying the content of the generated documentation
 If you want to modify the content of your generated documentation without changing the routes, go ahead and edit the generated `index.md` file.
 
-This file is located in the `source` folder of  your `output` directory (see [configuration](config.md#output)), so by default, this is `public/docs/source/index.md`.
+This file is located in the `source` folder of  your `output` directory (see [configuration](config.html#output)), so by default, this is `public/docs/source/index.md`.
  
 After editing the markdown file, you can use the `apidoc:rebuild` command to rebuild your documentation into HTML.