We worked on a project on the PHP Symfony with API Platform. This is pretty popular for API. As documentation, there was a bundle that generates OpenAPI docs from code. This seems very natural for developers, since most of the API is described declaratively in the annotations to the primary entities, and the bundle generates documents based on these annotations. In this way, documents represent what is in the code. But not vice-versa.
And so we discovered that some methods collect and return data that is not required by the front end, while also substantially loading the back end. We make the decision to remove this data from the particular method. In the framework, serialization groups are used to do this: labels are put on each field of the object to indicate in which contexts it should be issued. This all gets confused very quickly by haphazard grouping; therefore, we lost part of the valuable data while removing the unwanted data. Then we started to retrieve the lost data. We can discuss the details of the framework for a long time here, but in short, a few commits and a deployment on tests later, and we’ve a situation where the methods return an incomplete set of data, and no one knows exactly which one is complete. And the documentation shows not what should be, but what is now in the code.
And this is what we were left with:
- Edit data based on logic, but logic only applies to a certain area, whereas data is used in numerous areas. You dominate one place with logic and break two others. In the end, the testers are responsible for everything.
- Look at the front code. It could be one of them. It’s infested with bugs and does not inspire complete faith. Furthermore, you must divert the attention of the front-end developers. And the same issues as mentioned above.
- Checkout revision when we’ve not yet removed unnecessary data. However, because the application has a variety of logic, one dataset may have a slightly different appearance. So you need to look at different cases with full-fledged data and remove the structure from there. Also, keep in mind that this is initially a faulty code that we actually took to edit.
It’s clear that all of these alternatives are clearly cumbersome, unreliable, and inefficient in terms of labor costs. There was no other choice. And all that remained was to modify and test.
API documentation should be included in the design and the JSight project will finally overcome this problem.