code-orange/jot

Laravel package that generates RESTful API documentation in Markdown based on PHPDoc.

jot

Jot is a Laravel package that generates RESTful API documentation in Markdown based on PHPDoc., _(*1)

Installation

To install jot with composer:, _(*2)

composer require code-orange/jot

Laravel 5.5+

If you're using Laravel 5.5 or above, the package will automatically register the Jot provider., _(*3)

Laravel 5.4

Add CodeOrange\Jot\JotServiceProvider::class to the providers array in config/app.php., _(*4)

Configuration

You can use php artisan vendor:publish to publish the jot configuration to your application:, _(*5)

php artisan vendor:publish --provider=CodeOrange\\Jot\\JotServiceProvider

Then, update config/jot.php., _(*6)

Usage

Generating documentation

First, document your controller actions with PHPDoc., _(*7)

class MyController {
    /**
     * Returns a value
     *
     * This method returns a cool value.
     *
     * @param mixed $b Some value
     * @return JsonResponse {
     *                          "a": 1,
     *                          "b": "Example"
     *                      }
     */
    public function myAction(Request $r) {
        return response()->json([
            'a' => 1,
            'b' => $r->get('b')
        ]);
    }
}

Then, run php artisan jot:generate. Markdown documenting your API will be printed to your console., _(*8)

## Returns a value

This method returns a cool value.

`GET /example`

### Parameters

| Name | Located in | Description | Type |
| ---- | ---------- | ----------- | ---- |
|b|request|Some value|mixed|
|account|path|||

```json
{
    "a": 1,
    "b": "Example"
}
```

You can then add this Markdown to whatever you use to publish your docs. That can just be a Markdown file on GitHub, a wiki, or a self-hosted documentation site., _(*9)

The Markdown is compatible with lord/slate, which is what we're using at Odyssey to publish our documentation., _(*10)

Checking documentation coverage

Jot can also check if all of your public API methods are properly documented, for instance as part of your CI test pipeline., _(*11)

php artisan jot:coverage

will exit with an error status code if there is a method in your API that is not documented., _(*12)

Optionally, you can use --return to force all methods to have a documented return type/example., _(*13)

Motivation

This project is heavily inspired by f2m2/apidocs. While that project generates excellent documentation, I didn't like the idea of a Laravel app hosting its own documentation (something that can be done statically and that probably has much different access patterns)., _(*14)

Jot allows you to separate generation and publication of your API docs., _(*15)

Read more about building Jot in this blogpost., _(*16)