Fix examples syntax

[erwin1]

Fixed

• Fix examples syntax

---

[LucWollants]

@erwin1 I tried to verify this with Stoplight Version 2.3.0-stable.6547.git-2cf5b62 (2.3.0-stable.6547.git-2cf5b62.218309) but then the example is empty:

On the main branch I see two examples:

[erwin1]

I know... we can wait for Bert's input next week. But I think it's a bug in Stoplight Studio.

I had to change it because both stoplight studio and the github action were complaining about this.

With this change, those errors are gone and it works in the generated docs:
https://docs.publiq.be/docs/uitpas/c2NoOjExMTgyOTU5-error -> regular output
https://docs.publiq.be/docs/uitpas/branches/fix-error-tryout/c2NoOjExMTgyOTU5-error -> in a branch using this change. the examples are still there and actually nicer (with better names)

[LucWollants]

I am a bit confused but I think the example from the regular output or the main branch is correct:

The output from the new branch contains extra properties like summary and value:

[erwin1]

right. my bad. I'll re-iterate.

but one question: you don't see any issues if you include the Error.json from the main branch here?

[LucWollants]

but one question: you don't see any issues if you include the Error.json from the main branch here?

That works for me in Stoplight and the generated HTML

[erwin1]

and what about the openapi linting in Github actions?

[LucWollants]

I think that is fine on main if I check the last commit https://github.com/cultuurnet/stoplight-docs-errors/runs/4257264355?check_suite_focus=true

[erwin1]

The linting in this repo works indeed, but this Error is included in the uitpas docs and linting started failing: https://github.com/cultuurnet/stoplight-docs-uitpas/actions/runs/1462832435

My last commit seems to work in all cases.

• preview in Version 2.3.0-stable.6547.git-2cf5b62 (2.3.0-stable.6547.git-2cf5b62.218309)
• error checking in stoplight studio
• linting in uitpas Github actions

[bertramakers]

Using x-examples instead of examples on this model technically fixes it for UiTPAS, but it also breaks the examples themselves because Stoplight switched from using the non-standardized x-examples to the standardized examples starting with OpenAPI 3.1.0 files and JSON schema files (= individual models, which do not have an openapi version because they're just JSON schema files, and OpenAPI is basically an extension of JSON schema since 3.1.0).

So it "works" because using x-examples just makes Stoplight (and Spectral, the linting tool by Stoplight) ignore the property altogether.

You can see this in Stoplight Studio. For example on the main branch it shows 2 tabs with examples:

But on this branch it shows no examples:

I think there are a couple of solutions:

• Just remove the examples from this model. I've checked and we don't show this Error model anywhere directly anyway, so these specific examples are not visible for integrators anyway. Only the ones that we add to the actual error responses like Forbidden, Not Found, etc. (So basically the same end result as this PR, but without x-examples which doesn't do anything anyway)
• Change the openapi version in the UiTPAS OpenApi file to 3.1.0. (Which seems something we should do in the long run in general.) I tried this locally on the main branch and ran the linter again and it passed without any other changes, because from 3.1.0 on Stoplight expects "examples" instead of "x-examples". But maybe this change will give problems with your code generation @erwin1.
• Don't use the shared Error model in the UiTPAS OpenAPI file as long as it's OpenAPI 3.0.0. This one has the least preference IMHO.

[erwin1]

Change the openapi version in the UiTPAS OpenApi file to 3.1.0

I'll check the code generation with this

[erwin1]

Change the openapi version in the UiTPAS OpenApi file to 3.1.0

I'll check the code generation with this

seems like we're blocked on this:
OpenAPITools/openapi-generator#9083
which is blocked on:
swagger-api/swagger-parser#1535

So, let's remove the examples for now?

[bertramakers]

Okay removing the examples here seems like the easiest solution then. Was there anything else changed in this PR? Because the diff is a bit hard to follow.

[erwin1]

sorry, I must have reformatted it. fixed that now, and removed the examples