search

nextcloud / openapi-extractor

A tool for extracting OpenAPI specifications from Nextcloud source code
https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/ocs-openapi.html
GNU Affero General Public License v3.0
6 stars 2 forks source link

feat(ResponseType): Warn about top-level lists #153

Closed provokateurin closed 1 month ago

provokateurin commented 1 month ago

Closes https://github.com/nextcloud/openapi-extractor/issues/136

provokateurin commented 1 month ago

Usually it is fine to have a list as the top-level data structure and it makes sense in many cases, but if you ever need to extend it with something that is not part of the list you have to make a completely new and separate endpoint for it. For example if you have a pagination and want to return the cursor information in addition to the data, but previously you only returned the data. Since it is only a warning you are still free to ignore it.

nickvergessen commented 1 month ago

Since it is only a warning you are still free to ignore it.

I kind of disagree. If there are too many warnings people will ignore the warnings and miss out on real warnings.

For example if you have a pagination and want to return the cursor information in addition to the data, but previously you only returned the data.

You could follow industry standard praxis and add a header for "next page"?

provokateurin commented 1 month ago

I still think it is better to avoid top-level lists, but I'm fine with not warning about it. Developers should know what they are doing :woman_shrugging: