search

camaraproject / Commonalities

Repository to describe, develop, document and test the common guidelines and assets for CAMARA APIs
Apache License 2.0
9 stars 24 forks source link

Small component improvements & typo fixes #227

Closed maxl2287 closed 3 weeks ago

maxl2287 commented 1 month ago

What type of PR is this?

Add one of the following kinds:

What this PR does / why we need it:

This PR:

Which issue(s) this PR fixes:

Fixes #226

PedroDiez commented 4 weeks ago

I think it is a matter of swagger editor.

With redocly it renderizes OK:https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/Commonalities/b14810ac4c2183e27ead588fa44fd50b9a353a9a/artifacts/camara-cloudevents/event-subscription-template.yaml&nocors

If we think on adding it:

What i think we should not do is to define anything for "CreateSubscriptionDetail" object and remain empty:

maxl2287 commented 4 weeks ago

I think it is a matter of swagger editor.

With redocly it renderizes OK:https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/Commonalities/b14810ac4c2183e27ead588fa44fd50b9a353a9a/artifacts/camara-cloudevents/event-subscription-template.yaml&nocors

If we think on adding it:

  • Fine to fix some typos (e .g. "SUBSCRIPTION_MISMATCH") and some editorial enhancements
  • Fine to adding example in request (Line 50 and example from line 1099. I think for response it would be needed something analogous as it is also not shown in swagger editor (and we can check it works for both swagger and redocly) image

What i think we should not do is to define anything for "CreateSubscriptionDetail" object and remain empty:

  • The aim of this template is to be a baseline template for any project
  • "device" object is applicable only for some projects. Every project will define specifically the "CreateSubscriptionDetail" content based on its scope

@PedroDiez Yes you are right. It's just a problem on Swagger UI, which is not be able to handle discriminator examples. Redocly can do that pretty well.

So I decided to change this PR to just do the small improvements, without the example adding (as this would remove the examples with redocly).

PedroDiez commented 3 weeks ago

Thanks for the explanation @maxl2287, ok with the improvements