# Generating Documentation

To generate your API documentation, use the `apidoc:generate` artisan command.

```sh
php artisan apidoc:generate

```

It will generate documentation using your specified configuration. The documentation will be generated as static HTML and CSS assets within the specified output folder.

## Regenerating
When you make changes to your routes, you can safely regenerate your documentation by running the `generate` command. This will rewrite the documentation for only the routes you have changed. You can use the `force` option to force the regeneration of existing/unmodified API routes.

## Postman collections

The generator automatically creates a Postman collection file, which you can import to use within your [Postman app](https://www.getpostman.com/apps) for even simpler API testing and usage.

If you don't want to create a Postman collection, set the `postman.enabled` config option to false.

The base URL used in the Postman collection will be the value of the `base_url` key in your Laravel `config/apidoc.php` file. 

## 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.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.

```sh
php artisan apidoc:rebuild
```

## Automatically add markdown to the beginning or end of the documentation
 If you wish to automatically add the same content to the docs every time you generate (for instance, an introduction, a disclaimer or an authenticatino guide), you can add a `prepend.md` and/or `append.md` file to the `source` folder in the `output` directory, and they will be added to the generated documentation. 
 
 The contents of `prepend.md` will be added after the front matter and info text, while the contents of `append.md` will be added at the end of the document.
 
 ## Specifying language for examples
 For each endpoint, an example request is shown in [each language configured](config.html#example-languages). To add a language which is not supported by this package, you'll have to create your own view for how an example should render. Here's how:
 
 - Publish the vendor views by running:
 
 ```bash
 php artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=apidoc-views
 ```
 
 This will copy the views files to `\resources\views\vendor\apidoc`.
 
 - Next, create a file called {language-name}.blade.php (for example, ruby.blade.php) in the partials/example-requests directory. You can then write Markdown with Blade templating that describes how the example request for the language should be rendered. You have the `$route` variable available to you. This variable is an array with the following keys:
    - `methods`: an array of the HTTP methods for that route
    - `boundUri`: the complete URL for the route, with any url parameters replaced (/users/{id} -> /users/1)
    - `headers`: key-value array of headers to be sent with route (according to your configuration)
    - `cleanQueryParameters`: key-value array of query parameters (with example values) to be sent with the request
    - `cleanBodyParameters`: key-value array of body parameters (with example values) to be sent with the request

- Add the language to the `example_languages` array in the package config.

- Generate your documentation 

## Further modification

This package uses [Documentarian](https://github.com/mpociot/documentarian) to generate the API documentation. If you want to modify the CSS files of your documentation, or simply want to learn more about what is possible, take a look at the [Documentarian guide](http://marcelpociot.de/documentarian/installation).