search

dedoc / scramble

Modern Laravel OpenAPI (Swagger) documentation generator. No PHPDoc annotations required.
https://scramble.dedoc.co/
MIT License
1.24k stars 119 forks source link

Conditionals like whenExistsLoaded not recognized as optional #593

Open TiiFuchs opened 3 weeks ago

TiiFuchs commented 3 weeks ago

Hey,

I worked with spaties Laravel Query Builder package and since it allows with every relationship include to also include modelCount and modelExists, I implemented these in my ApiResource.

But since those are not always present I wrapped my count and exists like this:

[
  'relationship_count' => $this->whenCounted('relationship'),
  'relationship_exists' => $this-whenExistsLoaded('relationship'),
]

whenCounted seems to work just fine. Scramble recognizes it as an integer and does not mark it as optional (not required).

whenExistsLoaded does not work. It is not recognized as boolean and is marked as required.

There seem to be a few of these methods in the ConditionallyLoadsAttributes trait. Maybe there are more that make sense to implement in scramble.

TiiFuchs commented 3 weeks ago

Workaround for now is btw to switch it with a classic when like this:

'relationship_exists' => $this->when(isset($this->relationship), $this->relationship),
romalytvynenko commented 3 weeks ago

@TiiFuchs at the moment I'm working on more general solution for this issue. Will let you know when I'll have some updates!

TiiFuchs commented 3 weeks ago

Thanks! Appreciate it a lot!

Btw: I had a few urges to just manually change things to optional etc.

I think it's always good to have options to manually override (or set, if it's not automatically recognized) things... I did hope that something like /** @optional */ would work, but it didn't.

romalytvynenko commented 3 weeks ago

@TiiFuchs yeah, agree on that. Will add it. Is it a blocker for you? Or you've solved the issue with that workaround?

TiiFuchs commented 3 weeks ago

Workaround did it. No rush.

Happy to refactor as soon as there is an update.

seanburlington commented 4 days ago

A related issue I am having with conditionally loaded fields

I have articles and tags

The tag model has an articles relationship - so that I can find articles per tag

But also the tag model has an articles relationship - so that I can show the tags for an article

Now my documentation shows what looks like an infinite loop where you can drill down indefinitely.

Nothing seems to go wrong - but it looks really odd as you can never get to the end of the model.

I'm not even sure if this is a problem but I'd like it if people looking at my docs can tell that a response element may not be loaded.