Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 45 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,16 @@
Automatically generate beautiful API documentation for your Laravel API routes using annotations.

## Installation

PHP 7.4 and Laravel 7 or higher are required.

#### Installing

You will need LaRecipe to serve your autogenerated markdown

run
`composer require --dev binarytorch/larecipe && composer require --dev icodestuff/ladocumenter`
to download both LaRecipe and LaDocumenter as a dev dependency
`composer require --dev icodestuff/ladocumenter`
to download LaDocumenter as a dev dependency

Then
`php artisan larecipe:install` to install Larecipe
Expand All @@ -28,39 +30,50 @@ And lastly publish the config
`php artisan vendor:publish --provider="Icodestuff\LaDocumenter\LaDocumenterServiceProvider"`

## Demo Video

Here is a YouTube video showcasing the LaDocumenter package

[![Demo](http://i3.ytimg.com/vi/foBefSD3nQA/maxresdefault.jpg)](https://youtu.be/foBefSD3nQA)

## Getting Started
The only endpoints that are documented are the ones in your api.php file.

The only endpoints that are documented are the ones in your api.php file.

### Generating Documentation

In order to compile your annotations to markdown you will need to run:

`php artisan ladocumenter:generate`

### Grouping Endpoints
All endpoints are grouped for easy organization. Only use `@Group` to group endpoints in a single controller class by adding

All endpoints are grouped for easy organization. Only use `@Group` to group endpoints in a single controller class by adding
it to the top of the controller like so:
##### Example
```php
/**
* @Group(name="Foo", description="This is an example group.")
*/
class FooController extends Controller
{

}
```

##### Example

```php
/**
* @Group(name="Foo", description="This is an example group.")
*/
class FooController extends Controller
{

}
```

##### Attributes

- Name (required)
- Description (optional)

### Documenting Endpoints
The `@Endpoint` annotation is used for a single controller method or endpoint. *Note, at this time we don't support
closures or resources 😕*

The `@Endpoint` annotation is used for a single controller method or endpoint. _Note, at this time we don't support
closures or resources 😕_

#### Example

```php
class FooController extends Controller
{
Expand All @@ -69,21 +82,24 @@ class FooController extends Controller
*/
public function bar()
{

}
}
```

##### Attributes

- Name (required)
- Description (optional)

### Specifying Request Parameters
To specify a list of valid parameters your API route accepts, use the `@QueryParam` or `@BodyParam`.

Both the `@BodyParam` & `@QueryParam` annotation takes the name, type, required, description and an example.
To specify a list of valid parameters your API route accepts, use the `@QueryParam` or `@BodyParam`.

Both the `@BodyParam` & `@QueryParam` annotation takes the name, type, required, description and an example.

#### @BodyParam Example

```php
class FooController extends Controller
{
Expand All @@ -92,12 +108,13 @@ class FooController extends Controller
*/
public function bar(FormRequest $request)
{

}
}
```

#### @QueryParam Example
#### @QueryParam Example

```php
class FooController extends Controller
{
Expand All @@ -106,21 +123,24 @@ class FooController extends Controller
*/
public function bar()
{

}
}
```

#### Attributes

- Name (required)
- Type (required)
- IsRequired (required)
- Description (optional)
- Example (optional)

### Generating Responses

To generate a response, you must use the `@ResponseExample` annotation. This takes in the status of the response
as well as a link to the response file like so:

```php
class FooController extends Controller
{
Expand All @@ -135,15 +155,17 @@ class FooController extends Controller
```

##### Attributes

- Status (required)
- Example (required)


Be sure to add your responses to the storage directory as that is where LaDocumenter looks for them.
We recommend automatically generating responses using Laravel's testing suite.

### Indicating Authentication Status

LaDocumenter automatically labels an endpoint as authenticated if the route uses the middleware defined in the `config/ladocumenter.php` file:

```
'auth_middleware' => [
'auth:sanctum',
Expand Down
1 change: 1 addition & 0 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
},
"require": {
"php": "^7.4",
"binarytorch/larecipe": "^2.4",
"minime/annotations": "dev-master",
"myclabs/php-enum": "^1.7"
},
Expand Down
Loading