Swagger

What is it?

"Swagger (...) [builds] beautiful and interactive API documentation (...) by asking your API to return a YAML or JSON that contains a detailed description of your entire API. This file is essentially a resource listing of your API which adheres to OpenAPI Specification." [source]

Setup

1. Install the package with ./vendor/bin/sail composer require "darkaonline/l5-swagger" (in wsl terminal) or composer require "darkaonline/l5-swagger" (in the php container)

2. Publish it with ./vendor/bin/sail artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider".

3. In the /app/.env file, add L5_SWAGGER_CONST_HOST='http://localhost/api'.

4. In the main Controller /app/app/Http\Controllers\Controller.php, add the @OA\Info annotation:

/**
 * @OA\Info(
 *   version="1.0.0",
 *   title="API documentation",
 * )
 */
class Controller extends BaseController
{
}

5. Describe each endpoint with the @OA\[METHOD] annotation. Example:

namespace App\Http\Controllers\API;

class AuthController extends APIController
{
	/**
	 * @OA\Post(
	 *   path="/api/auth/sign-up",
	 *   operationId="signUp",
	 *   tags={"Authentication"},
	 *   @OA\RequestBody( ... ),
	 *   @OA\Response( ... ),
	 * )
	 *
	 * Registers a new user.
	 *
	 * @param Request $request
	 * @return JsonResponse
	 */
	public function signUp(Request $request): JsonResponse
	{
	}
}

6. After every change, run ./vendor/bin/sail artisan l5-swagger:generate to regenerate /app/storage/api-docs/api-docs.json.

Usage

Open http://localhost/api/documentation to view and interact with the API.