API description formats, like Swagger, act as a contract between the API provider and end consumer — clearly detailing all of the resources and operations of the API in a format that’s both human and machine readable. Using Swagger to document your RESTful APIs enables easier development, better discovery, and an overall better integration experience for the end consumer. As a provider using Swagger to define an API, you have the responsibility to keep that contract up-to-date, which often requires managing multiple versions of your Swagger definition. Or, if you are someone that's following a "code first" approach to Swagger — which means having to use annotations to generate the Swagger spec from the code of your API — you may find that there are some tweaks needed to create a well-designed definition for your API. Whatever approach your team follows to define your API with Swagger, there’s a good chance there are a number of different people, with different skillsets and responsibilities, involved in the process.
Involving the right people in API documentation
Developers and API designers aren’t the only one’s involved in the design and documentation phases of the API lifecycle. If your team is serious about documenting your API, you likely have a technical writer whose responsibility it is to improve your API’s usability by providing concrete documentation to work with your API’s various resources. That person may not be actively involved in the initial development of the API, and as a result will often have to invest a lot of time understanding how to write a description for an API endpoint that is accurate and provides the right amount of context for the end user. This documentation workflow involves a lot of collaboration between the developer, technical writer, and anyone else involved in publishing the API. And also requires the right amount of traceability to ensure that nothing breaks when making an update to the definition.
The right tools for your documentation workflow
Here at SwaggerHub, we’ve worked hard to provide tools to make it easier for all of the members of your team to work together throughout the lifecycle of your API. With features like comments and team management, you can get feedback, raise questions, and resolve issues in real-time. And now, we are excited to announce our newest improvement to SwaggerHub, which will make it even easier to compare Swagger definitions, review and verify changes, and accept updates to your Swagger spec.
Introducing Compare and Merge for SwaggerHub
Whether you’re updating a Swagger definition that’s already in use, or adding Swagger to an existing API, it’s helpful to compare the changes you’re making before you update the API. You can compare and merge your API specification stored in SwaggerHub with another API spec that is stored in a YAML or JSON file in your file system, be it from your local machine or to another definition stored in SwaggerHub. Unlike a traditional diff & merge solution, the SwaggerHub Compare & Merge feature is built specifically for reviewing and implementing changes to the Swagger definition. It provides the right amount of feedback and will help validate that your API is accessible, based on the changes you’re making to the definition. Here’s a closer look at how the Compare and Merge tool works: Compare with a Swagger definition in SwaggerHub
- In SwaggerHub, open your API for editing. Switch to the needed version.
- Click the "gear" icon in the top right corner of the editor and select Compare and Merge API from the menu:
- In the subsequent dialog, select Compare to Spec in SwaggerHub:
- In the next dialog, specify the user name, API and the API version for comparison:
To compare the API with another version of the same API, enter your user name, the API name and choose another version.
- Click Next. SwaggerHub will validate that the API is accessible.
If the validation is successful, click Next again. This will invoke a window where you can see the difference between the APIs. Compare with a Swagger file
- In SwaggerHub, open your API for editing. Switch to the needed version.
- Click the "gear" icon in the top right corner of the editor and select Compare and Merge API from the menu.
- In the subsequent dialog, select Compare to an external Spec
- In the next dialog, enter the URL of the desired JSON or YAML API, or specify the API file on your hard drive:
- Click Fetch. SwaggerHub will load the specified API and check if it is valid.
If the loaded API is valid, click Compare. This will open a window where you can see the difference between the APIs (see below). If the loaded API in invalid, you will see a message describing the problem. Below is a sample view of the Difference Window: 
Your API is on the right, the “other” API is on the left. SwaggerHub automatically detects and highlights the changed lines. The Diff Type setting at the bottom of the window specifies the differences that SwaggerHub highlights:
| Value |
Description |
| Design + Metadata |
SwaggerHub highlights the differences in property values and new and deleted nodes. |
| Design only |
SwaggerHub highlights only changes in the specification structure which affects the operations of the API. Differences in descriptions, examples, and other human-modified documentation will not be highlighted. |
Merging Differences
- Click the highlighted difference line (or block) in the right or left part of the window. SwaggerHub will copy the block from the left side of the window to the right side (that is, to your API) and will remove highlighting. It will also increase the counter in the Undo button.
- Click Undo to revert the most recent approval, if needed. To revert several approvals, click Undo several times.
- After you merge all the needed differences, click Save Changes to save the changes. This will replace your API specification with the changed one.
If you wanted only to view the differences (that is, to compare two API specifications), click Cancel. The Compare and Merge feature was added to improve the workflow of updating and editing APIs in teams. If you have any more suggestions for new features, please feel free to send us a feature request here.