API specification generation

[romalytvynenko]

Hey 🙌

This PR introduces automatic API specification generation using Scramble.

How it works

dedoc/scramble is required as development dependency. For spec generation testbench is used: ./vendor/bin/testbench scramble:export creates the specification file.

How CI part works

Using GitHub Actions, dedoc/scramble-pro is installed (provides support for packages the API is built with) and after that the specification can be generated (scramble:export).

Next, a very opinionated step happens. GHA clones docs repository into a subfolder. Then, the API specification file is being generated in that newly created docs repository folder (docs-repository/api-reference/openapi.json). After that, GHA commits and pushes changes (if any) to the docs repository. This can be improved though! I imagined something like pushing to some dedicated branch of docs repo and creating a PR from that branch (if not existing), so the maintainers can manually accept the updated specification.

This step is very opinionated and I was curious if I can make it work. If keeping the spec file within this repository is fine and it will somehow then be moved to docs repository, I will drop this part!

Notes

1. Currently the core and CI depends on development branches of Scramble. This is due to me finding the generated API specification inaccuracies – I want to update Scramble to fix/improve such inconsistencies. After that is done, I tag versions an use them.
2. I removed redundant annotations from controllers. However the documentation for API parameters is pretty valuable. And currently there is no attribute in Scramble that allows you to do that. So I am going to implement such attribute and use it. Let me know if removing existing annotations here is not okay, I will roll back the change.

Further improvements

• Ensure PHPStan is happy
• If a constant is referenced in allowedIncludes (or other methods; for example ->allowedIncludes(self::ALLOWED_INCLUDES)), the corresponding expected parameters are not documented
• Add a way to document parameters manually with #[Parameter(...)] and #[QueryParameter(...)], ... etc attributes
• Think an decide about how JSON:API should be documented (optional attributes, links, meta etc).
• Remove Request suffix from the laravel data objects that are used only as a requests

The generated specification demo: https://elements-demo.stoplight.io/?spec=https://gist.githubusercontent.com/romalytvynenko/b0c750bc3f66177b488913d8bc1dcf34/raw/b4b28031d148b84a3ea873d5c624775f8b67ceae/spec3.json

Let me know what you think!

[jbrooksuk]

@romalytvynenko this is so good, thank you!

We'll keep this in draft until Scramble has the new features merged, so we're not pinned to a specific branch.

[romalytvynenko]

Just as a small update, working on that Request suffix issue 🙌

[romalytvynenko]

@jbrooksuk just wanted to let you know that I've released alpha versions of Scramble and unpinned this implementation from branches!

While I will continue working on improving Scramble so it covers Cachet's API better, this branch can now be reviewed and merged 🙌

[jbrooksuk]

First, quick pass at a review.

[jbrooksuk]

We need to update these to the real docs and main branch.

[jbrooksuk]

I think we can replace this with the setup-git-user workflow, https://github.com/marketplace/actions/setup-git-user

[romalytvynenko]

Hmm, could not make it work, but found this gem used in other Cachet's workflows! I'll use it

https://github.com/stefanzweifel/git-auto-commit-action

[jbrooksuk]

Suggested change

	uses: actions/checkout@v2
	uses: actions/checkout@v4

[jbrooksuk]

Suggested change

	uses: actions/checkout@v2
	uses: actions/checkout@v4

[jbrooksuk]

Suggested change

	$openApi->info->description = 'API documentation for Cachet, the open source status page system.';
	$openApi->info->description = 'API documentation for Cachet, the open-source, self-hosted status page system.';

[romalytvynenko]

Applied the requested changes!

[jbrooksuk]

Let's go!