DC-570: Update swagger to reflect new schema validation #157
Conversation
Abulu123
changed the title
There was a problem hiding this comment.
Seeing a JSON schema, JSON example, and stringified JSON example all defined separately makes me concerned that a future change to the schema would not fully propagate to all of those places, leading to inconsistent documentation.
Had you considered consolidating to a single JSON schema with embedded examples, and/or referencing your example in common.openapi.yaml?
| examples: | ||
| jsonObject: | ||
| summary: A sample object |
There was a problem hiding this comment.
I've looked into this more and I think we should be able to get externalValue to work. The problem is that the index.html that ships with swagger doesn't support it yet. See swagger-api/swagger-ui#5433
For now, you should look at the example HTML solutions on that GitHub issue and add one to our copy of index.html (which is in service/src/main/resources/templates).
| @@ -0,0 +1,192 @@ | |||
| { | |||
| "dct:title": "sint", | |||
There was a problem hiding this comment.
Since it wasn't obvious how to generate this example, can you document the steps to do it somewhere, such as in a file in the docs directory.
| @@ -103,7 +103,7 @@ | |||
| }, | |||
| "contributors": { | |||
| "type": "array", | |||
| "items": { "$ref": "#/defs/contributor" } | |||
| "items": { "$ref": "#/$defs/contributor" } | |||
|
Kudos, SonarCloud Quality Gate passed!
|
| @@ -103,7 +103,7 @@ | |||
| }, | |||
There was a problem hiding this comment.
Can you fix this one too? The line above this should be
"$ref": "#/$defs/samples"
Not sure why we're not seeing errors in our app due to typos like this. Maybe we need to be loading the schema in a stricter mode, if one exists.
|
I've moved these changes to #162 |
No description provided.