Add custom attributes to changelog entries basing on OpenAPI extension tags
anikitin opened this issue · comments
In our OpenAPI specs we use a number of custom vendor extension tags which are set at the level of operation.
These are additional classifiers which help to group APIs one or another way.
Today oasdiff creates a changelog in JSON format and has "operation", "operationId" and "path" for each item.
My request is also support adding extra attributes basing on x-tags defined in original OpenAPI spec.
For example, I can have "x-audience: Public" defined in the spec at operation level.
Would be nice to have a config option which instructs oasdiff to copy certain xtags as attributes into resulting changelog JSON entry.
The rationale behind it is the following. We render changelog JSON as HTML table. So having extra columns which allows to quickly filter or sort basing on original classifiers from OpenAPI spec would help to analyze large changelogs.
Example:
OpenAPI fragment (YaML):
"/restapi/oauth/token":
post:
operationId: getToken
x-audience: Public
summary: ...
requestBody:
...
responses:
...
Changelog fragment:
[ {
"id":"new-optional-request-property",
"text":"added the new optional request property ivr_pin'",
"level":1,
"operation":"POST",
"operationId":"getToken",
"path":"/restapi/oauth/token",
"source":"new-openapi.yml",
"x-audience": "Public"
}]
Another helpful improvement would be detecting changes in these custom OpenAPI tags defined at operation level (simplest).
So in the example above, oasdiff could detect if "x-audience" is changed from "Private" to "Public".
Hi @anikitin ,
To make sure I understand correctly, there are two requests for enhancement here:
- Allow including specific Specification Extensions in the changelog output for json/yaml formats
- Allow including specific Specification Extensions in the diff and changelog
Is this correct?
Can we assume that the values are always strings or could they also be: null, other primitives (number, bool), an array or an object?
(I just noticed that I haven't submitted my reply on this one, sorry about it)
@reuvenharrison , yes, you are right, I was writing the ticket about (1) and realized that (2) may be also helpful.
In our particular case x-tag values of interest can be of string or boolean type. Also they can be omitted for some operations (which may be treated as null, we don't indicate null values explicitly). At the same time I can see some value in supporting it for any primitive types. Would be more complex for arrays/objects and honestly such scenarios are unlikely and less straightforward.
Another question:
Suppose x-audience was modified from Public to Private.
Which value would you expect to see in the output?
@reuvenharrison , good question.
When it is included as a metadata value for a changelog (case 1), it has to contain the new actual value.
When it is included in the diff/changelog (case 2), both old and new values should appear as usual.
@reuvenharrison , do you want me to test with pull request first or are there any plans including it into official release?
Thanks.
There is still some work to do before testing.