search

belgif / rest-guide

REST Guidelines of Belgian government institutions
https://www.belgif.be/specification/rest/api-guide/
Apache License 2.0
24 stars 4 forks source link

Add rule for description and summary #152

Open jpraet opened 9 months ago

jpraet commented 9 months ago

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

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 commented 9 months ago

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

pvdbosch commented 9 months ago

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 commented 7 months ago

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

jpraet commented 6 months ago

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 commented 3 months ago

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.