Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add custom attributes to changelog entries basing on OpenAPI extension tags #451

Open
anikitin opened this issue Dec 2, 2023 · 6 comments · May be fixed by #467
Open

Add custom attributes to changelog entries basing on OpenAPI extension tags #451

anikitin opened this issue Dec 2, 2023 · 6 comments · May be fixed by #467
Labels
enhancement New feature or request

Comments

@anikitin
Copy link

anikitin commented Dec 2, 2023

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".
@reuvenharrison reuvenharrison added the enhancement New feature or request label Dec 12, 2023
@reuvenharrison
Copy link
Collaborator

reuvenharrison commented Dec 12, 2023 •
edited

Hi @anikitin ,
To make sure I understand correctly, there are two requests for enhancement here:

  1. Allow including specific Specification Extensions in the changelog output for json/yaml formats
  2. 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?

@anikitin
Copy link
Author

(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.

@reuvenharrison
Copy link
Collaborator

reuvenharrison commented Dec 23, 2023 •
edited

Another question:
Suppose x-audience was modified from Public to Private.
Which value would you expect to see in the output?

@reuvenharrison reuvenharrison linked a pull request Dec 25, 2023 that will close this issue
changelog-custom-attribute #467
Open
@anikitin
Copy link
Author

@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.

@anikitin
Copy link
Author

@reuvenharrison , do you want me to test with pull request first or are there any plans including it into official release?
Thanks.

@reuvenharrison
Copy link
Collaborator

There is still some work to do before testing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement New feature or request
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

changelog-custom-attribute Tufin/oasdiff
2 participants
@anikitin @reuvenharrison