TDD or Test-Driven Documentation

[ajcastro]

Hi, I just like to share this idea.

This is a documentation principle where you generate your api docs by running phpunit tests instead of docblocks annotations in the controller.

Benefits

• Updating your tests updates your docs automatically.
• Better workflow, instead of writing docblock annotations and parameters in controller, you can auto-generate documentation from the tests performed.
• Less comments or visual debt in controller codebase. (Some annotations are still needed but annotations can be put in the test classes instead)
• Follows the principle "If it is not tested, it does not exist." making sure your docs and test are in sync.

Currently, there is a package that has this principle/workflow, called Enlighten, https://github.com/StydeNet/enlighten/.
But scribe output looks better and easier to navigate.
Scribe output has more fun features like the "Try it out".
Scribe has support for OpenAPI and Postman collection.

So I am wondering if scribe can adopt test-driven documentation so I can drop Enlighten.

[shalvah]

That's an interesting idea. I don't see myself exploring it anytime soon because I don't have the bandwidth right now, but you can always send in a proof of concept.

Theoretically, you could add it to the existing Scribe architecture as a new strategy, say GetDetailsFromTests. A limitation of this is that it will be run once for each endpoint, so you have to only run the tests for that endpoint.

A second limitation is that the strategy has to be registered with a specific stage (headers, query parameters etc), but it's easy to get around that by mutating the $endpointData object directly.

[ajcastro]

Hi @shalvah , thanks that you like the idea!
Maybe I can ask the author of Enlighten if he is interested to collaborate and help us implement the feature he has done in Enlighten. I hope he would help us for the sake of the open-source community. If ever, I am also interested to help to implement that feature.

[ajcastro]

Hi, @shalvah I plan to work on this, do you have a public repository that uses scribe? So I can start to familiarize myself and deep dive into how it works. It would be better if the repo is using most of the features of scribe. Although I also created a sample laravel app and installed scribe but it would be faster if I can look on others work.

[ajcastro]

I found it, haha. https://github.com/knuckleswtf/TheSideProjectAPI

[shalvah]

Yeah, it's slightly out-of-date, but I'll be updating it in a few hours.

[ajcastro]

Scribe-TDD is ready for testing. I was hoping we can get some other beta testers. https://github.com/ajcastro/scribe-tdd.
I am also testing it on my end.

[ajcastro]

@shalvah when will be the patch released? for the RouteDocBlocker::getDockBlocks().

[shalvah]

Tagged 3.5.2.👍

Nice work. 👏

Noticed in the docs you have // ... in the config, which implies (to me) the user should add your custom strategies to the ones already present. Aren't they supposed to replace them entirely?

[shalvah]

Reopening to remind me to mention this in the docs.

[ajcastro]

Thanks @shalvah !

Noticed in the docs you have // ... in the config, which implies (to me) the user should add your custom strategies to the ones already present. Aren't they supposed to replace them entirely?

I am thinking not to replace them entirely because there are default strategies that seem to be better.
For example, I prefer the default strategy for urlParams because it convert the urlParam api/users/{user} to api/users/{id} and it already has a description.

I also like the feature of the default strategy of bodyParams in formRequest or inline validation where it includes the validation rules to the description.

So I think that the strategies can be a combination of both the default strategies and tdd strategies. Currently, I am leaving the options for others to choose their preferences.

[shalvah]

Mentioned this in the docs: https://scribe.knuckles.wtf/laravel/documenting

[ajcastro]

@shalvah thanks a lot!