Release notes automatization

[DenTray]

It would be very helpfull to have an abulity to see chnages list between the each documentations change.

On each save documentation - we may set some version to the new documentation file and save the difference to the version.

We also need to find a way how to display these changes.

[vitgrams]

@DenTray I have done research on this issue. We can rewrite the code of this library in php to get a difference between the documentation versions for Swagger (v1, v2). There is also a version of this library for Open API Specification (v3), also written in Java. I also found a very useful plugin for the Phpstorm IDE and Visual Studio, which automatically shows the difference after selecting two versions of the documentation. There is one significant drawback of the tool. It cannot compare the description property of parameters. If the validation rules for a specific parameter change (except for the required rule), then we will not see this in the report.

[DenTray]

@vitgrams great thanks for your investigation! About the generating file of the doc difference, could you please generate some example using the Java library? For this please make the following:

1. Generate documentation using Laravel swagger package with at least 2 API.
2. Make the next changes in the API:

• Remove 1 of existed API
• Create at least 1 new API
• Change the API's response code, and input body params by adding new input, removing existed input and updating rules for some of input fields

3. Generate updated documentation file
4. Generate the difference from the documentation files.

After finish with the example file - please try to find some free templates which can display the changes in the browser. I believe that IDE plugins are good but it will works only for developers team and force to install some additional tools which are not the best solution.

[vitgrams]

@DenTray Generated documentation diff for two API versions. The results have been attached. Could you please take a look? swagger-diff.zip

[DenTray]

@vitgrams thanks a lot! I believe such view is enought. Let's port java code to the php inside the Laravel-Swagger package

[DenTray]

@vitgrams we need to do the following

1. On each documentation saving - check difference between the last version
2. If changes not empty - increase doc version and save new documentation with changes from the last doc
3. I believe we can store doc in the DB with fields: version, documentation, changes
4. Implement separate route to view the list of documentations and changes

[vitgrams]

@DenTray Branch 66_implement_swagger_diff_module with related changes has been pushed to remote as discussed.