Creating API documentation with OpenAPI / Swagger in Laravel Projects

This tutorial describes how to API documentation with OpenAPI / Swagger in Laravel (6 or later) projects.
Provided by Leumas Naypoka /


What is API Documentation?

API documentation represents a technical content deliverable, containing instructions about how to effectively use and integrate with an API. In other words, generally tt's a concise reference manual containing all the information required to work with the API. This manual has to include detailed description about the functions, classes, return types, arguments and more, supported by tutorials and examples.

Traditionally API Documentation is creating by using regular content creation and maintenance tools or text editors.

What is API Specification?

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.

When OAS is properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

What Is Swagger?

Swagger allows you to describe the structure of your APIs so that machines can read them. The ability of APIs to describe their own structure is the root of all awesomeness in Swagger.

Why is it so great? While reading API's structure, we can automatically build beautiful and interactive API documentation. We can also automatically generate client libraries for your API in many languages and explore other possibilities like automated testing. Swagger does this 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.

Swagger-Core Annotations

If you want to generate the Swagger documentation, swagger-core offers a set of annotations to declare and manipulate the output. The swagger-core output is compliant with Swagger Specification. A user is not required to be familiar with the full aspects of the Swagger Specification in order to use it, but as a reference it may answer a few questions regarding the generated output. Annotations may be grouped into three - the annotation to declare the resource, the set of annotations to declare an operation, and the set of annotations that declare API models.

Package Installation

To install package for Laravel, run following command:

$ composer require --dev zircote/swagger-php

Create directory

Add this directory to .gitignore file:

Write Swagger code annotations and run following command to generate Swagger UI files. After creating Swagger UI will be accessible via

Run Laravel artisan command:
php artisan swagger:api-docs

Working Flow

1. Add Swagger annotation in each API enpoint. For example:

     * @OA\Post(
     *     path="/register",
     *     tags={"Users"},
     *     operationId="userRegister",
     *     summary="Register new user",
     *     @OA\RequestBody(
     *         required=true,
     *         @OA\JsonContent(ref="#/components/schemas/RegisterRequest")
     *     ),
     *     @OA\Response(
     *         response=201,
     *         description="User registered",
     *         @OA\JsonContent(ref="#/components/schemas/SuccessProfileResource")
     *     ),
     *     @OA\Response(
     *         response=204,
     *         description="User not registered",
     *         @OA\JsonContent(ref="#/components/schemas/ErrorProfileResource")
     *     )
     * )
     * Register new user
     * @param  Request  $request
     * @return JsonResponse
public function register(RegisterRequest $request)
        if (
$user $this->service->register($request)) {
"success" => "Check your email and click on the link to verify."
], Response::HTTP_CREATED);
        } else {
], Response::HTTP_NO_CONTENT);

2. Generate Swagger UI documents locally.

swagger example

3. Export Swagger UI documents to SwaggerHub.

swagger hub

To be continued...


Please post only comments related to the original tutorial. Be polite and helpful, do not spam or offend others.
Create Your Free Account
Please remember that this information is essential to use our services correctly.
After creating the account you will be able to download all of our FREE products.
Fields marked with * are mandatory

Please send me information about updates, new products, specials and discounts from ApPHP!
We recommend that your password should be at least 6 characters long and should be different from your username/email. Please use only letters of the English alphabet to enter your name.

Your e-mail address must be valid. We use e-mail for communication purposes (order notifications, etc). Therefore, it is essential to provide a valid e-mail address to be able to use our services correctly.

All your private data is confidential. We will never sell, exchange or market it in any way. Please refer to Privacy Policy.

By clicking "Create Account", you are indicating that you have read and agree to the ApPHP Terms & Conditions.

Quick Registration with: Facebook / Google