Static / manual documentation for routes

[NiclasvanEyk]

• [x] I've read the documentation and I can't find details on how to achieve this.

Sometimes one has no control over the docblocks for certain endpoints. Laravel Fortify for example provides endpoints for Login, while the concrete responses and parameters for each of those endpoints is defined by the using application in Actions. Other libraries also provide endpoints, which most likely won't always come with proper annotations for scribe.

It would be really helpful to have some kind of strategy or place in the config file where one can statically annotate certain endpoints. Looking at the code for \Knuckles\Scribe\Extracting\Strategies\Metadata\GetFromDocBlocks, it seems to extract the fields 'groupName', 'groupDescription', 'title', 'description' and 'authenticated'. These could be supplied for a route statically by defining a key with the route path or name or another identifier and pass field data manually/statically.

Pseudo code:

// config/scribe.php

return [
    // ...

    // the name can definitely improved upon
    'include' => [
        '/auth/login' => [
            'metadata' => [
                'groupName' => 'auth',
                'groupDescription' => 'Everything related to login and authentication',
                'title' => 'Try to log into the application',
                // ...
            ],
            'urlParameters' => [/* ... */]
            'queryParameters' => [/* ... */]
            'headers' => [/* ... */]
            'bodyParameters' => [/* ... */]
            'responses' => [/* ... */]
            'responseFields' => [ /* ... */],
        ],
    ],

    // ...
];

I know one could easily write a plugin for this, but I feel that this is such a common use case, that it would make sense to include it in the core. Especially as so many first-party packages define their own routes (e.g. for authentication), which is vital to a team consuming the application / api.

[shalvah]

I've read the documentation and I can't find details on how to achieve this.

You sure? 👀

https://scribe.knuckles.wtf/laravel/architecture#what-are-those-yaml-files-for

They're not a perfect solution, but I don't know that the config file is either. It would easily get really big, and it's not the kinda stuff you put in a config file.

[NiclasvanEyk]

You can add new endpoints. This is useful if you're using a package that adds extra routes (like Laravel Passport), and you want to document those. Custom endpoint files use a slightly different format from regular endpoints, so Scribe automatically adds an example custom.0.yaml file to the .scribe/endpoints folder, and you can edit it to add additional endpoints.

Sorry, totally missed this, it even explicitly talks about it

[NiclasvanEyk]

While I was totally wrong, I think this (very useful!) feature would be better surfaced when it would be mentioned somewhere in the "Documenting your Api" part instead of in the "How it works" section. Maybe including an example .gitignore entry that ignores all autogenerated files but keeps the .scribe/endpoints/custom.*.yaml files to make it easier for the reader to add these overrides without the need to check in the whole .scribe folder.

But as others seem to have found this anyways feel free to ignore it, maybe I just did not look hard enough :sweat_smile: Thanks four your time!

[shalvah]

While I was totally wrong, I think this (very useful!) feature would be better surfaced when it would be mentioned somewhere in the "Documenting your Api" part

Yeah, you're right. I'm sure I mentioned it elsewhere though. I'll double check.

[shalvah]

As for Git, it's debatable. If you edit the other endpoint files too (which you can), you'd probably want to keep them in Git.

[shalvah]

Here ya go: https://scribe.knuckles.wtf/laravel/documenting/custom-endpoints