Improving the Swagger Docs for Management API

[OwainWilliams]

Hi,
I've been doing a lot of work with the Management API recently and as useful as it is, I believe it could be improved upon. I was going to start making a PR to add Endpoing Descriptions on each endpoint. This is going to be a big task so before I did start, I wanted to check, is it something that would be appreciated?

What I'm suggesting is instead of this :

[HttpGet("children")]
    [MapToApiVersion("1.0")]
    [ProducesResponseType(typeof(PagedViewModel<DocumentTreeItemResponseModel>), StatusCodes.Status200OK)]

have

[HttpGet("children")]
[MapToApiVersion("1.0")]
[ProducesResponseType(typeof(PagedViewModel<DocumentTreeItemResponseModel>), StatusCodes.Status200OK)]
[EndpointDescription("Get all children of a parent document by passing the parent id to the endpoint")]

This would then show up in the Swagger Docs and gives more useful information.

e.g. An example of what I've done with a custom endpoint.

If this would be welcomed, then I could maybe find others to help with this task so that the docs are updated as quickly as possible

[AndyButland]

I don't see any reason why this wouldn't be welcome @OwainWilliams - thanks for the offer. @kjac - just checking with you if you see any downside to this? Also @hifi-phil - would this be of any benefit to for the MCP server?

[bjarnef]

Can EndpointSummary be used, while EndpointDescription for a longer description?
https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/include-metadata?view=aspnetcore-9.0&tabs=minimal-apis

Difference in Swagger UI: https://stackoverflow.com/a/78090722

https://swagger.io/docs/specification/v3_0/grouping-operations-with-tags/

[hifi-phil]

@AndyButland, no i don;'t see any downsides to this at all. It will help the Management API become easier to understand.

For the Dev MCP product we will likely not use these added descriptions for tool descriptions, as these need to be specific for AI use and update-able separately from the Management API so that we can quickly and separately optimise for performance.

[OwainWilliams]

@bjarnef I just tested this and yes, both work

As you'll see in the screenshot, the Summary shows on the closed accordion view and the Description is given within the body of the accordion

[bjarnef]

Yeah, the summary may be useful to give a short descriptive text to get an overview without expanding each endpoint, while the description allows a more detailed explanation of the endpoint.

It seems summary allows a maximum of 120 characters:
OAI/OpenAPI-Specification#832

[OwainWilliams]

I'll see if I can find time to start working on this. Maybe take on one of the smaller areas first and build it up from there.

[kjac]

@OwainWilliams this would be very welcome indeed ❤️

We put in the work to document the Delivery API, but not the Management API - simply because we couldn't anticipate its adoption outside of the CMS core itself, and thus we couldn't really justify the time spent.

You might be able to lift some ideas from the Delivery API Swagger docs... although they're likely a bit more comprehensive than the Management API Swagger docs will be, since adding examples to the entire Management API will be a monstrous task.

[OwainWilliams]

Just looking at the best way to attack this - if I fork the repo as usual, I might get on socials and see if anyone else wants to join me in getting this updated. What's the best way to do this, people fork from my branch and then it's a single PR?

[AndyButland]

That would work, but might be a bit of a pain for you and others to keep updated with main, and it'll end up with one very big PR for review, with perhaps quite a bit of back-and-forth given the subjectivity around wording of descriptions.

So might be better to take one management API endpoint group - e.g. data types - and create one PR to update that, that can be reviewed and merged. And then you'll have an example to point to for others that may want to help, by tackling another endpoint group and creating an PR for that.

The only downside of that is consistency - we'll have some endpoints documented and some not for a quite a while. But I don't think that's a big issue, and you could argue that any documentation is better than no documentation, so the sooner the updates trickle in, the better.

[OwainWilliams]

Thanks Andy - that was my concern that some was done and some wasnt but I agree, some is better than none and if some is done, it might encourage others to update.

[OwainWilliams]

This could be a long process but it has started :)