How to convert the Jira WADL documented to OpenAPI/Swagger definition
Platform Notice: Data Center Only - This article only applies to Atlassian products on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
Nowadays many applications are using REST APIs as the default interface to expose data for interchange. Because of that it is much more complex to find what is available and how to integrate the applications. To centralize the specifications of the applications an API management platform is used to import for example the Jira REST API definition. An API management platform is a tool used to access, distribute, control, and analyze APIs used by developers in an enterprise setting. A well knows documentation format used is OpenAPI. The OpenAPI Specification, previously known as the Swagger Specification, is a specification for a machine-readable interface definition language for describing, producing, consuming, and visualizing RESTful web services.
Environment
8.x
9.x
Diagnosis
The Jira platform REST API resources are also documented in this WADL file: jira-rest-plugin.wadl. Please refer to REST APIs and the following link replacing the 9.6.0 in the URL for the Jira version you want could be used to download the specification WADL file: https://docs.atlassian.com/jira/REST/9.6.0/jira-rest-plugin.wadl.
Cause
The Jira REST API is documented using a WADL file format and does not follow the OpenAPI specification.
Solution
The content on this page relates to API document specification conversions using external tools. The content is out of the scope of our Atlassian Support Offerings. Consequently, Atlassiancannot guarantee support. Please be aware that this material is provided for your information only and you mayuse it at your own risk.
Use the SOAPUI tool for importing the Jira WADL and converting it to OpenAPI/Swagger format specification.
Note that you need to use a modified WADL removing the spaces in the element field as mentioned in JRASERVER-40063: WADL element names contain spaces.
Download the jira-rest-plugin.wadl.
Open in a text editor the jira-rest-plugin.wadl file to remove all the spaces from theelement=for example from element="Listof field" to element="Listoffield" and save the file.
Import it into SOAPUI > Menu File > New REST Project > Import WADL... button > Inform the changed jira-rest-plugin.wadl file path.
Export as OpenAPI/Swagger from SOAPUI > Menu Project > Export Swagger/OpenAPI Definition > Select the newly created project from the imported file e.g. Jira 9.6.0 > enter the Target File path with the extension e.g. JiraOpenAPI.json > Ok.
The Postman tool could be used to import the JiraOpenAPI.json to be sure it is correctly converted.
Open Postman, select the workspace > APIs > click on + (plus signal: Create new API) > expand the new API definition created > Definition > on the right panel, select Import Definition > Select the JiraOpenAPI.json > Import button.
Was this helpful?