External File Annotations

[pirex360]

I don't know if this is a question labelled issue or a feature request...

So, this is my problem : I have an extensive documentation API, my controllers are big because of the annotations /** ... */ ...used to create the documentation, is there a way to put the information of the annotation in a remote file to separate logic and be better maintained?

note: I already put the body and query parameters in the FormRequests classes to reduce the annotations lines in the controller...but for the custom blocks of text of every endpoint ... a simple controller with 3 or 4 methods... easily has more than +1000 lines.

Is there a way to put this annotation in other external files? and call dynamic something like:

/**
* ...
* @include annotations.clients.store`
* ....
* /

[shalvah]

I see your problem. Right now, there's no option for that, beyond @responseFile for responses. . I'm generally against adding any new annotations, but perhaps. I'm thinking of an

/**
* ...
* @include_docs path/to/file
* ....
* /

What would the structure of the external file be like though?

[pirex360]

Hi, the include_docs, could be a simple blade template file (HTML Support), but if it's more simple just text file or markdown.

[shalvah]

Taking a look at this; I can see benefits in that it also communicates to other devs. One problem though-is this one file per endpoint? I can see that getting out of hand pretty quickly. If it's multiple endpoints per file, it might then be difficult to manage/specify.

[pirex360]

Ok, maybe one file for Controller ? I understand that one file per endpoint could be in some large projects unmanaged, but I personally don't see this as deal breaker, maybe we can choose our way, one file per endpoint or per controller, it may be on a specific folder... And optional.

I revisited some project with this package, and I have huge controller line s because of the documentation, even with parameters docs shifted to FormRequest files.

If we can find a way to resolve this problem, our Controllers will be smaller and cleaner, and maintaining the docs will be clear and not a mess.

And of course thank you for addressing this problem.

[shalvah]

I personally don't see this as deal breaker,

That's the nature of software. As a consumer, you don't see the problem, because you see only your specific use case.🙂

Let's say one file per controller. One key problem with combining endpoints in one file is how do you identify and reference them? In practice, the implementation wouldn't be too hard, but as maintainer, I have to think about the design first, and how I can find a good balance for myself and consumers. For instance:

• What kind of file would that be?
  • Markdown: How would you separate the various endpoints in the file? With headings? What would the heading name be? How brittle would that be against e.g. typos?
  • YAML: This is probably the best option, since it's a structured format, but then you'd have to write long texts and Markdown inside the YAML, and I don't think that's super fun.
  • PHP: Most structured option. Great for me as the maintainer, but probably not cool as a user; writing long texts in PHP with be even less fun.
  • Blade: How would that even work? Also same problems as Markdown.
• How would you reference the specific section in the file? Should Scribe auto match by HTTP method and path? What happens if you change the path, but forget to update the file? Or should we require an explicit reference in your docblock? If so, what would that syntax be like, to be intuitive? How would it avoid brittleness?