This project shows how Swagger can be integrated into a Laravel project using the L5-Swagger package. This demonstration is part of the ongoing engineering talks over at Pixel Fusion, a digital strategy and product development studio based in Auckland, New Zealand.
:fire::fire: DEMO HERE :fire::fire:
Note: The database resets every hour
According to their own blog post:
Swagger is a set of rules (in other words, a specification) for a format describing REST APIs. The format is both machine-readable and human-readable. As a result, it can be used to share documentation among product managers, testers and developers, but can also be used by various tools to automate API-related processes.
It has been an ongoing constraint for API developers to communicate (let alone present) the features of an API-driven product to internal & external stakeholders (who most of the time don't even know what APIs are). Swagger provides a intuitive web interface where users of various disciplines, whether it be front-end, back-end, business development, and all those in between, can easily understand (and test) the features of an API-driven product.
api-docs.json file after running the php artisan l5-swagger:generate command. This gist provides some good examples of Swagger annotations. This is particularly useful for those just scratching the surface of how Doctrine annotations are written.On this project, annotations have been segmented on these paths:
| Type | Location |
|---|---|
| Metadata | app/Http/Controllers/Api/Controller.php |
| Paths | app/Http/Controllers/Api/**/* |
| Definitions | app/Models/**/* |
Why not just put all the annotations/definitions on a single file?
While that is possible, some developers (myself included) prefer "spreading out" annotations to where they semantically belong. It also makes more sense to spread out the annotations when working with team members. For this project, I added path annotations on top of controller files (some put theirs on route files) and definition annotations on model files. Running php artisan l5-swagger:generate then scans the entire application directory for annotations and generates an api-docs.json file, where all API definitions and paths are placed.
Is Swagger enough to test APIs if they work?
Swagger is used primarily for documenting API endpoints, not testing them. For that, you'll need to write integration tests through tools like Behat or Codeception.
I don't like the default theme, can I customise it?
Definitely! You can write a theme from scratch or, like most people, try and test free templates like these.
When I update an annotation, how do I generate new docs
You'll need to run php artsan l5-swagger:generate in order to generate a fresh api-docs.json. Additionally, we recommend generating a configuration file with php artisan l5-swagger:publish-config so you have more control over the package's configuration.