Creating API documentation with OpenAPI / Swagger in Laravel 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...