openapi-diff: Description & summary of Operations not showing in changelog.

Description

I’ve been testing what this library can and cannot do, and it appears that it does not keep track of description & summary of the operations?

I have also tested this with the description of parameters, and they do update.

It does show the summary directly after the path of the operation, but it only shows the latest one and it does not show it has been changed.

The code

  /pets/{id}:
    get:
      description: A description    // This is not in changelog when changed
      summary: This is a summary    // This is not in changelog when changed
      operationId: find pet by id
      parameters:
        - name: aaadda
          in: path
          description: Param desc   // This is in changelog when changed
          required: true
          schema:
            type: integer
            format: int64

Question

Am I correct in that those properties are not in the Changelog? Or am I making a mistake.

About this issue

Original URL
State: closed
Created 6 years ago
Comments: 20 (20 by maintainers)

Commits related to this issue

Suggested fix for https://github.com/quen2404/openapi-diff/issues/60 — committed to msnijder30/openapi-diff by msnijder30 6 years ago

Most upvoted comments

I don’t know, i have some idea to improve code, and it will break the current api. So I want to make this changes before release 2.0.0 ! Not big changes, but enough to break compatibility !

quen2404 on Nov 6, 2018

Snapshot version is not available currently 😐

quen2404 on Nov 5, 2018

@msnijder30 i only add support in diff result, not on the ouput (markdown, html, console). Because i’m working on another branch to improve the output globally (not only for summary/description)

quen2404 on Nov 5, 2018

I’m working on it in the branch feature/summary-description, but work is in progress.

quen2404 on Oct 26, 2018

Hello, i opened the project this morning ! I’m working on it !

quen2404 on Oct 25, 2018

Hi, I had some time, looked at the code and made something.

What’s new

I’ve added the classes OperationMetadataDiff and ChangedOperationMetadata. These classes keep track of changes made in summary & description.

I’ve also added the setting showChangedMetadata to MarkdownRenderer, which is false by default, this is the option which will enable descriptive changes.

The changed markdown

As you can see there is an Metadata field as first item below the operation. This contains the summary & description. If only the summary has changed it will only show the summary, same for the description.

If showChangedMetadata is enabled and if there are changes the markdown file looks as follows:

#### What's Changed
---

##### `GET` /pets/{id}

> This is a summary

###### Metadata:

Changed summary : `Old summary` to: 
> `This is a summary`

Changed description : `Returns a user if the user does not have access to the pet` to: 
> `A description`

###### Parameters:

Added: `aaadda` in `path`
> Param desc

Deleted: `id` in `path`
> ID of pet to fetch

Example code

MarkdownRender renderer = new MarkdownRender();
renderer.setShowChangedMetadata(true);

String md = renderer.render(diff);

All commits related to this feature

cd827cff4588a33ac4e85f38213d45abb7387954 (Changed OpenApiDiff to have more Lombok)
be1c577fffae977c312fb56741e1d4c6f85df9ec (First working version)
1da0e19bf9ae00c779d5afd37a499b48171edac6 (Final working version)

Questions

What do you think of this?
What do you think of the name metadata to describe the summary & description?
Is the formatting of the markdown acceptable?
In ChangedOperationMetadata#isChanged I’m not sure if there also should be an INCOMPATIBLE option since it is compatible with OpenAPI 2.0 but not with OpenAPI 1.2, in 1.2 there is no description field. It should be backwards compatible though since it will just see that the description field is null and will not include it into the changelog. summary should still work.

Looking forward to your reaction, if you think this is a good idea I’ll make a pull request, if you have any suggestion for changes I’ll add those.

If you think it’s a bad idea that’s okay aswell 👍

msnijder30 on Oct 19, 2018

It depends on what is your definition of quick 😉 I’m a little busy today and this weekend, but i think i will have time to do this next week.

quen2404 on Oct 19, 2018

Ok, in my company we only use the Markdown output. I will update HtmlRender to output the same details. But as i mentionned in my previous response, this kind of changes are only descriptive. I understand you want to see all changes in the changelog 😃 So as a compromise, we can add an option to output this kind of descriptive changes in the changelog !

quen2404 on Oct 19, 2018