Home
Tutorials
Laravel Api Documentation With Openapi Swagger

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 / www.apphp.com

Content

API Documentation
API Specification
What Is Swagger?
Swagger-Core Annotations
Package Installation
Working Flow

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


public/api/swagger/

Add this directory to .gitignore file:


public/api/swagger/*

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


http://your-site-domain/api/swagger

Run Laravel artisan command:


php artisan swagger:api-docs

Working Flow

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


<?php
    /**
     * @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)) {
            return response()->json([
                "success" => "Check your email and click on the link to verify."
            ], Response::HTTP_CREATED);
        } else {
            return response()->json([
                "error"=>Response::HTTP_NO_CONTENT, "message"=>"Unauthorised"
            ], Response::HTTP_NO_CONTENT);
        }
    }
?>

2. Generate Swagger UI documents locally.

3. Export Swagger UI documents to SwaggerHub.

To be continued...

Comments

Please post only comments related to the original tutorial. Be polite and helpful, do not spam or offend others.

Members Login