Defining and fine tuning an API in Laravel with the Stoplight Platform

Stoplight Platform is a series of tools that makes API design and documentation super easy. Their Studio product is an OpenAPI editor. Prism allows you to create a mock HTTP server to generate sample data based on your design specification. The Elements project creates documentation from your OpenAPI specification file. At Bluehorn Digital, we used Stoplight Studio to fine-tune an API provided by a Laravel (Lumen, actually) application.

I want to share how we used Stoplight Studio to customize the default Laravel model serialization API. I used Studio to create the API design and specify adjustments needed to the Laravel models (casts, date formats) and required fields in our controller request validation when creating new models. Studio also allowed us to provide documentation that could be handed off to the consumer! The consumer was also able to begin writing their integration application using the HTTP mock server provided by Prism. 💥

Note you don’t need to use Stoplight’s products or tools. You could use the Swagger Editor or any other OpenAPI tools. I like the Spotlight Platform the most.

This could be considered “backward,” in that we didn’t design the API first in an OpenAPI specification and then write the server code. However, life isn’t always perfect. In our case, we had existing Laravel models and an API that we needed to expose to a new third-party consumer, where the API was entirely consumed by our own frontend. The…