Swagger and Laravel

This page will summarize how to set up and integrate Swagger into an existing, Laravel based microservice. This guide assumes a moderate knowledge level, so if you’re an absolute beginner, you might want to skip this one.

About Swagger:

If you wish to read more about the magic documentation software, what it is, and how it works – click the following link: https://swagger.io/

Setup procedure

This guide assumes that you have an up-and-running Laravel based project, with a version of 5.5 or above. 

Run the composer function, from within your docker container:

 composer require "darkaonline/l5-swagger:5.7.*"

Please note: The version above is specific to your Laravel configuration, if you’re working with a newer/older Laravel setup, use the corresponding swagger version: Link → https://github.com/DarkaOnLine/L5-Swagger

Publish the configuration:

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

That’s it, you have the generator configured. Now, there are two ways to generate the documentation. If you would like for the generation to be done automatically, add the following line to your .env file:

L5_SWAGGER_GENERATE_ALWAYS=true

Otherwise, simply run the following command, once you’ve added all of your annotations (or at any other time really, there’s no limit  )

php artisan l5-swagger:generate

Annotations:

The annotations are what goes inside of your controllers, and are what the generators rely on, to produce an api-doc. A full list of these annotations can be found, by browsing the following links:

https://github.com/DarkaOnLine/L5-Swagger/blob/master/tests/storage/annotations/OpenApi/Anotations.php

https://github.com/DarkaOnLine/L5-Swagger/blob/master/tests/storage/annotations/Swagger/Anotations.php (This syntax requires an additional installation candidate! )

If you would like to read more about OpenApi, and become a guru master, click this link: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md

A very helpful example, compiled by the team behind Swagger, can be found here: https://github.com/zircote/swagger-php/tree/master/Examples/petstore-3.0

Otherwise, some notes that might be helpful:

1. Your parent controller must include the “OA\Info” key. It’s usually best to have the annotation added to the parent controller, as it makes things easier, when you need to change something later
2. You should describe all possible return scenarios. This includes any 200/401/500 etc. errors. Note that you might need to describe what exceptions are thrown as well
3. Be very careful when writing-out the parameters to a path, this might stop other devs from being able to run tests via Swagger UI
4. Triple-check your paths. This might seem obsolete, in terms of information, but it’s super important. Any mismatch, will break your gorgeous OpenApi docs.

Example api-doc:

Here’s a simple generated document, describing a DB Healthcheck function (formatted in JSON):

{
    "openapi": "3.0.0",
    "info": {
        "title": "Some API documentation",
        "description": "I'm a description",
        "contact": {
            "email": "[email protected]"
        },
        "version": "1.0.0"
    },
    "paths": {
        "/healthcheck": {
            "get": {
                "tags": [
                    "healthcheck"
                ],
                "summary": "A DB connection test function",
                "operationId": "check",
                "responses": {
                    "200": {
                        "description": "Healthcheck passed"
                    },
                    "500": {
                        "description": "Healthcheck failed"
                    }
                }
            }
        }
    }
}

Example Parent controller notations:

Here’s an example annotation of a parent controller, which is extended by all of the other controllers. By placing the annotations here, we ensure that they are applicable to all of the other controllers, even if they’re added later on:

/**
 * @OA\Info(
 *      version="1.0.0",
 *      title="Some API ",
 *      description="Another description, whoa",
 *      @OA\Contact(
 *          email="[email protected]"
 *      )
 * )
 *
 *  @OA\Server(
 *      url="http://localhost:8080/api/1",
 *      description="Dev server"
 *  )
 *
 *  @OA\Server(
 *      url="http://staging.com/api/1",
 *      description="Staging server"
 *  )
 *
 *  @OA\Server(
 *      url="https://production.com/api/1",
 *      description="LIVE server"
 *  )
 */

The above is added at the very top of the controller, before any other definitions. The added Server definitions, ensure that we can change the environment, when testing the endpoint.

Accessing the UI:

Swagger UI is built-in to the darkaonline package, we installed. Simply navigate to:

http://www.your-project.com/api/documentation

Final notes:

Some more information about Swagger UI: https://swagger.io/tools/swagger-ui/

A super handy editor, where you can check the validity of your api-doc, and see it in all of it’s glory: https://editor.swagger.io/

Happy coding! 

Homepage