RESTful APIs are the digital glue that connect modern IT systems together and require proper documentation.
Companies often struggle with creation and management of their APIs due to design flaws that appear too late to get fixed at moderate cost. Adequate documentation is also key for API maintenance to establish a common understanding of current and future features among all stakeholders.
Normally you would not create a specification yourself but use an established specification framework instead. OpenAPI Specification and RAML (RESTful API Modelling Language) are the two market leaders in this area.
Deciding which one you use will also decide what visualiser or editor you can use, a key consideration. If you want to convert existing API documentation (for example to use a different visualisation tool) there is a package which can help you do this called oas-raml-converter-cli.
yarn global add oas-raml-converter-cli// NPM
npm install -g oas-raml-converter-cli
To run the CLI utility run the following command after installing:
- Start the utility via
oas-raml-converter-cliin the terminal and you will see this:
Choose the type of converter you want to use (enter option 1-5):1) RAML 0.8 > RAML 1.0
2) RAML 0.8 > OAS 2.0
3) RAML 1.0 > OAS 2.0
4) RAML 1.0 > OAS 3.0
5) OAS 2.0 > RAML 1.0Enter now:
2. After choosing your option select the source file (the utility will check if it exists before continuing):
Enter the source path of the file:
3. Enter a destination path. If the folders do not exist the application will create them. Ensure you have adequate permissions in your target destination:
Enter the destination path for the file:
4. A final prompt before performing the conversion, press (y) to continue or (n) to abort:
Are you sure you want to continue (y/n):
And thats it, your file should now be converted. You will be able to convert any version of Open API to RAML and vice versa as many times as you like!
If you have any comments please write them below, thanks for reading!