Add rule for description and summary

[jpraet]

Should there be a rule for description, summary, title of operations/schemas/other? Start with upper case and end with a period (.)

• https://support.smartbear.com/swaggerhub/docs/en/manage-resource-access/api-standardization.html#UUID-a3ec554d-e289-65b4-198a-7c68403402d4_id_summary-format
• https://github.com/Azure/azure-openapi-validator/issues/59

In the belgif types it's not very consistent:

https://github.com/belgif/openapi-problem/blob/2caf79a89d933d01d222046724ca0698d775cd53/src/main/openapi/problem/v1/problem-v1.yaml#L17

https://github.com/belgif/openapi-problem/blob/2caf79a89d933d01d222046724ca0698d775cd53/src/main/openapi/problem/v1/problem-v1.yaml#L23

https://github.com/belgif/openapi-problem/blob/2caf79a89d933d01d222046724ca0698d775cd53/src/main/openapi/problem/v1/problem-v1.yaml#L45

[pvdbosch]

title for Schemas should probably be avoided, because they override the Schema name in the SwaggerUI view

[pvdbosch]

there's already a rule for description (and avoid title) on schemas: [oas-descr]

I'll check if absence of title property is verified by the validator

[pvdbosch]

Absence of title property is added in new release of validator >= 1.3.0 (though validator not yet open-sourced)

[jpraet]

Maybe we should discourage putting summary and description on path level instead of operation level.

The spec https://spec.openapis.org/oas/v3.0.3#path-item-object states that summary and description on path level are intended to apply to all operations in the path.

But swagger-ui does not render them (https://github.com/swagger-api/swagger-ui/issues/5653), not even as a fallback when the summary or description on operation level are absent.

I think it's also more logical in general to put the summary and description on operation level.

[pvdbosch]

Personally, I prefer start with a capital letter, but a period seems unnecessary for single-line summaries.

It might not be worthwhile to enforce such guidelines very strictly. It could represent more work than gain depending on the context of the API. There are always some exceptions that should be allowed (e.g. description: "eHealth-ID of software package"). It would be interesting if the validator would support configurable rule sets for such cases.