A Swagger documented REST API

23 May 2016 - by 'Maurits van der Schee'

"A fully documented REST API" in five minutes? With Swagger you can! Simply upload "api.php", configure the database and load up the PHP script. You will see a huge JSON object in your browser. This is the Swagger 2.0 standardized description of your generated API (based on your database structure). The good part? You can point the Swagger UI tool to this URL and it will make beautiful documentation for you, like this one. You can also Copy/Paste the JSON code into the Swagger editor to customize it. In the main menu of the editor choose "File" and then choose "Paste JSON...".

Beyond documentation

Why not scaffold the entire back-end? I honestly don't know why not. I extended the Swagger definition a bit and added "x-references", "x-referenced" and "x-primary-key" as optional properties to the fields in the response object. Then I started coding. Although it is far from finished, I have already committed a first version that shows pretty well what the application will feel like. I added a bit of Bootstrap 3 for a slick look. It feels fast, documented, API-first, but admittedly a bit "generated".

Customization options

To allow you to replace the "generated" feel with some sophisticated "custom made software" feel I will add customization options. Currently I am thinking about the following callbacks:

table_name_formatter: to pretty print the name of a table
column_name_formatter: to pretty print the name of a column
column_formatter: to pretty print the name of a column value
input_field_formatter: to customize rendering of the input field
reference_formatter: formatting references in hyperlinks/dropdowns

It will also be possible to override the header and footer to fully customize the layout used. The file is named "ui.php" and can be found on the PHP-CRUD-UI Github repository.

To meta program or not to meta program

This type of software has the huge advantage that it consists of less lines of code and that it gets you started fast. In my experience most business software does more or less the same, so this approach makes sense. Fellow programmers may try to convince you that their project is very special, but more often than not it isn't. Most people simply need: relational data, a fully documented API and a UI to modify the data (styled in company colors and preferably based on the API). This software tries to provide all of that with little code and customizable to satisfy your customer. It does not yet have authentication (yet), but that is easy to add.

Links

PS: Liked this article? Please share it on Facebook, Twitter or LinkedIn.

TQ
dev.com