Skip to content

Add endpoint descriptions to the management API #20689

@AndyButland

Description

@AndyButland

Umbraco's management API exposes provides many endpoints for CRUD and other operations on Umbraco entities. They are all defined in the Umbraco.Cms.Api.Management project in controllers under the Umbraco.Cms.Api.Management.Controllers.

Each public action method in the controllers support two attrbutes: EndpointSummary and EndpointDescription. The former is intended for short description of the endpoint and the latter for a longer one.

In #20549 these attributes have been populated for a small subset of controller methods.

We'd like to apply these same attributes to all management API controller action methods with appropriate short and long descriptions. You should use the attributes populated in the linked PR as good examples for the types of descriptions we would like to use. The descriptions should all use the same tense (e.g. "Gets a data type" rather than "Get a data type"), use similar phrases when describing similar concepts like "pagination" or "collection", be punctuated consistently and contain a similar amount of detail.

EndpointSummary should be one short sentence. EndpointDescription should be a maximum of three sentences.

The aim should be to not create an undue burden on ourselves going forward in describing every field or parameter, and to avoid repeating something that's already easily available in the Swagger UI that shows request and response models and parameters. We should try to give details on the end result of the operation describing what calling the method means in terms of the system behaviour.

Avoid adding descriptions to those that already have them in #20549, but please add them to all of the others.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions