Download the PHP package johnylemon/laravel-apidocs without Composer

Laravel API documentation generating tool

The problem

I don't like writing tons of lines of stupid annotations just to have hope that api documentation will be generated correctly without errors that says nothing. And I am not the only one. More.

This package solves this problem the way I like - by writing PHP code.

The solution

This package adds apidocs method to Laravel routes, where you can define route definitions using code you use every day.

This way you can:

• reuse, extend and modify existing api definitions
• create generic endpoint definitions and just modify them ad-hoc or by creating child classes
• define multiple examples
• define multiple sample responses
• define and reuse parameter definitions
• make your controllers readable again

Getting started

1. Add johnylemon/laravel-apidocs repository

2. Register Johnylemon\Apidocs\Providers\ApidocsServiceProvider provider if not registered automagically .

3. Install package. This command will publish all required assets.

4. Enjoy!

Generating route documentation

This package ships with command for rapid route definition generation.

Brand new SampleEndpoint class will be placed within app\Apidocs\Endpoints directory. Target directory may be changed within your apidocs config file.

This class contains only one describe method, where you have to use any of available methods that will describe your endpoint. Like that:

As you can see we set title and description as endpoint definition. Every method returns endpoint instance so you can chain them.

Endpoint available methods

• uri
• method
• group
• deprecated
• title
• description
• desc
• query
• params
• body
• header
• headers
• example
• examples
• returns

uri

Set uri. Called under the hood during endpoint mounting

method

Set endpoint method. Called under the hood during endpoint mounting

group

Add endpoint to specific group. Group have to be defined previously.

deprecated

Will mark endpoint as deprecated.

title

Set endpoint title

description

Set endpoint description

desc

Alias for description

query

Defines endpoint query params. See: parameters

params

Defines endpoint route params. See: parameters

body

Defines endpoint body params. See: parameters

header

Defines endpoint header

headers

Defines multiple endpoint header at once

example

Defines endpoint example. Optionally you can define example title

examples

Define multiple endpoint examples at once

returns

Define sample return value with status code. OPtinally you may define response description.

Additionally you can use methods like returns201 (or any other status code)

Endpoint definition usage

Okay, you created your first endpoint definition. Now it's time to use it as some real route definition.

Lets assume you have following routes:

If you want to use App\Apidocs\Endpoints\SampleEndpoint class as definition for first of them you should simply do this:

and... yes, thats it!

The only thing you have to do now is to call php artisan apidocs:generate command and visit /apidocs route to see it in action!

:warning: This package must clear route cache to generate apidocs properly. If you are using route caching in your production environment rememeber to call artisan route:cache after artisan apidocs:generate command

Because apidocs method returns endpoint class, you can chain methods during route definition. For example, you may want to mark your route as deprecated:

And because deprecated method returns endpoint as well, you are allowed to use other endpoint methods.

:warning: After calling apidocs method you cannot use route-specific methods, like, say, name method. Be sure to call apidocs method after all framework route-specific methods are called.

Resource routes

Sometimes you would like to use resource or apiResource methods to create bunch of typical CRUD endpoints. To specify definitions for these endpoints you have to use their names:

As you can see, you may ommit endpoints you dont want to be documented.

Sometimes you may be using resources or apiResources methods to create bunch of CRUDs at once. Because Laravel does not provide any handy hook for that, routes defined that way (and any other named routes!) may be documented using apidocs helper:

As metioned earlier, you may ommit endpoints you don't want to be documented.

Parameters

Some routes contains route parameters, like {user} segment. Sometimes you also want to use required or optional query parameters. Routes like POST, PATCH, PUT almost always expects some payload.

You can define them using params, and pass them as array to query, body and params method when describing endpoint.

Lets assume your index route from previously presented routes expects optional page parameter.

Your definition should now contain additional query method call with array of possible parameters. After that your code will look like that:

Note that we did not specify parameter name (page) by array key. It is not necessary when you define parameter name within class. But of course you can define them in different way:

As you can see, when parameter name is defined in both, array key and param name, array key will take precedence allowing you to create reusable custom parameters.

Route parameters and request body parameters can be defined same way.

Available methods

• type
• name
• description
• desc
• required
• optional
• enum
• possible
• default
• example
• eg

type

Define parameter type

name

Define parameter name

description

Define parameter description

desc

Alias of description. See description

required

Mark parameter as required

optional

Mark parameter as optional

possible

Set parameter possible values

enum

Alias for possible. See possible

default

Set parameter default value.

example

Set parameter example.

eg

Alias for example. See example

Param class makes use of magic __call method and allow you to define parameter type and name at once by using one of these methods: string, array, boolean, bool, integer or int

Custom parameters

It is common case that you may use page or some other param in different endpoint definitions. So it may be cumbersome to write something like that over and over again:

To solve that problem you may define PageParam, which you can reuse as many times as you want without repeated code:

Creating custom parameters

Custom parameters may be created by typing

New param class may be defined within __construct method:

Groups

Apidocs endpoints will be groupped. If no group is specified, default non-groupped group will be used.

You can define your own groups using Johnylemon\Apidocs\Facades\Apidocs facade:

Groups must be defined before route registering. Perfect place for that is the the very beginning of your routes file.

Commands

This package ships with some commands that will be used for common tasks:

Testing

You can run the tests with:

License

The MIT License (MIT) Please see LICENSE for details.

Contact

Visit me at https://johnylemon.dev

Next

• improve examples
• improve responses
• improve resources
• improve layout

Developed with ❤ by johnylemon.