Laravel Swagger Demo
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.
Note: The database resets every hour
❓ What is Swagger and why use it?
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.
Frequently asked questions
- How do you generate docs?
Firstly, you need to create annotations that Swagger can parse and turn into an
api-docs.jsonfile after running the
php 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:
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
pathannotations on top of controller files (some put theirs on route files) and
definitionannotations on model files. Running
php artisan l5-swagger:generatethen scans the entire application directory for annotations and generates an
api-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 run
php artsan l5-swagger:generatein order to generate a fresh
api-docs.json. Additionally, we recommend generating a configuration file with
php 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.