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.
🔥🔥 DEMO HERE 🔥🔥
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.
- How do you generate docs?
Firstly, you need to create annotations that Swagger can parse and turn into anapi-docs.jsonfile after running thephp artisan l5-swagger:generatecommand. 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 addedpathannotations on top of controller files (some put theirs on route files) anddefinitionannotations on model files. Runningphp artisan l5-swagger:generatethen scans the entire application directory for annotations and generates anapi-docs.jsonfile, 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 runphp artsan l5-swagger:generatein order to generate a freshapi-docs.json. Additionally, we recommend generating a configuration file withphp artisan l5-swagger:publish-configso you have more control over the package's configuration.
- Swagger Pet Store API docs demo
- DarkaOnLine/L5-Swagger - Laravel package for integrating Swagger
- Swagger annotation reference
- Doctrine Annotations reference
- Converting Swagger Definitions to Postman Collections
- What is Swagger and why use it?
- Good annotation practices (e.g. where to put them, how they are read).
- Where to place annotations.
- A working demo (deployed thru either Beanstalk or Forge).
- Examples of well-thought Swagger docs.
- Annotation proper.
- Artisan commands.
Laravel Passport, which gives the framework the ability to act as an OAuth2 server, is already installed and configured on this installation.Actually, due to time constraints, I'll go with publicly accessible endpoints for the meantime.