knuckleswtf / scribe

Generate API documentation for humans from your Laravel codebase.✍
https://scribe.knuckles.wtf/laravel/
MIT License
1.75k stars 314 forks source link

Laravel sorting and inheritance. #527

Closed I2EJeffrey closed 2 years ago

I2EJeffrey commented 2 years ago

I have updated scribe to 4.0.0 to use the groups/subgroups. Thing is, I can't seem to make it work.

I nest the endpoints as described in the documentation but instead of them getting nested/added to the 'drop down' in the sidebar on the docs page they just move to the bottom of the sidebar.

Part of the scribe.php -> groups -> order config

            'Event' => [
                'Event Accommodation Date' => [
                    'List Event Accommodation Dates',
                    'Create Event Accommodation Date',
                    'Get Event Accommodation Date',
                    'Update Event Accommodation Date',
                    'Delete Event Accommodation Date',
                ],
                'Event Accommodation Location' => [
                    'Add accommodation location to event',
                    'Get event accommodation location',
                    'Remove accommodation location from event',
                ],
            ],

What am i doing wrong here?

shalvah commented 2 years ago

Can you share a picture of what your sidebar looks like?

I2EJeffrey commented 2 years ago

image

All of the 'Event' stuff gets put on the bottom whilst it should be between 'Endpoints' and 'Item'. It also does not look sub-grouped to me.

shalvah commented 2 years ago

What happens when your groups.order is empty? Also, I don't know if this is just for the example, but your sidebar has "Events", while the group name in the config you shared is "event".

shalvah commented 2 years ago

Also, can you share an example of how you're defining groups and subgroups on your endpoints? Are you using @group/@subgroup?

I2EJeffrey commented 2 years ago

Welp I apparently completely overlooked that part of the documentation where it talks about @group/subgroup sorry about that. Problem is fixed

I2EJeffrey commented 2 years ago

I do actually have another question, is there a way to 'nest' subgroups? so it would be

Group
 > subgroup
     - subgroup
     - subgroup
 >subgroup
shalvah commented 2 years ago

I'm sorry, but my answer is "Hell no!"😂

For real, though, supporting subgroups wasn't a small task. If you look closely, you'll notice that endpoints aren't grouped under subgroups, it's just an extra property on the endpoint object, with some extra work to make it appear grouped in the UI. I'm not saying it wouldn't be possible to support another level of nesting (what would you call that? @subsubgroup), but it's not something I look forward to doing (nor will I have the time for it anytime in the next year, at least).

You could try for yourself, though. Every EndpointData object has a field called $custom. With a custom strategy and some UI customisation, you could probably hack it.

I2EJeffrey commented 2 years ago

That is completely fair and I didn't expect you to add it at all! I was just curious if it was a possibility. Guess I'll try and figure out a custom strategy.