Category: Product Engineering
Last updated on May 12, 2023
As a software development team, you might have spent endless hours building and refining your API, ensuring it meets the needs of your users and integrates efficiently with other systems. However, you’ve noticed that documenting your API effectively can be a time-consuming and error-prone task, specifically frequent. You might have also realized that having accurate and up-to-date API documentation is critical to your user’s success and satisfaction with your product.
To address these challenges, we’ve recently launched a new feature that lets users import their API definitions directly into your platform, giving them clear prominence in the API’s endpoints, parameters, and response codes. This feature has already generated positive user feedback, but you want to take it a step further and make it even more robust and handy to use.
To that end, we’ve introduced a command-line tool called d360, which allows developers to import or resync their API definitions directly from their CI/CD pipelines. This tool automates the documentation process, ensuring that the documentation is always up-to-date and in sync with the API code. We’ve also taken care to ensure that the tool is flexible, customizable, and integrates seamlessly with other development tools and services.
In this blog, we’ll take a closer look at the challenges of documenting APIs, the benefits of using command-line tools like d360, and how to use d360 in your own development workflow. We’ll provide examples of the commands available in the tool and explain how to set up the tool in your CI/CD pipeline. By the end of this blog, you’ll have a clear understanding of how d360 can help you streamline your documentation process and ensure that your users have the information they need to successfully use your API.
As part of the developer’s toolkit, command line tools provide a fast, flexible, and powerful way to handle commands in all kinds of environments. Here are a few reasons why command line tools are useful:
Our d360 CLI tool is designed to meet all the above-mentioned requirements, ensuring that your resync process can be automated in a fast and efficient manner.
Currently, we have published our tool in NPM (short for Node Package Manager) is a package manager for the JavaScript programming language. It is used to manage and share packages of code that are written in JavaScript/Typescript and can be used in various applications.
For better versioning of this package, we have followed a process called Semantic Release. It involves analyzing the changes made in a project’s source code repository, determining the type of release based on the nature of those changes, and automatically updating the project’s version number and creating a release in the appropriate format (e.g., a Git tag or a release on GitHub).
Basically, let’s say you have your OAS spec file in your repository, you already might have a CI/CD pipeline that takes care of your building and deployment of your APIs. During this build process, you just need to add two commands which take care of resyncing your API definition to Document360.
npm install d360 -g d360 apidocs:resync –userId=<Enter User ID> --apiReferenceId <Enter API Reference Id> --apiKey <Enter API Key> --path <File path or URL>
If you add the above two commands, the resync will be done in a smooth manner.
Using this tool exclusively in your CI/CD flow is not mandatory. As an NPM package, you have the option to install it directly onto your local machine, allowing you to execute both commands seamlessly.
Also Read: 6 Best API Documentation Tools for 2023
Currently, there are two commands available in our tool,
By utilizing the ‘apidocs’ command, you will have the ability to generate API documentation directly from your API Definition file.
d360 apidocs --apiKey=c92e71ab-ebdf-4007-89ed-5d47493052cd --userId=3340e95e-2b68-4a3f-a8c9-124bcaec9972 --versionId=d486783f-b833-446e-aa71-615ac51392c3 --path=https://petstore.swagger.io/v2/swagger.json
Options | Description |
apiKey string | Project API Key |
userId string | User Id that’s used to generate API Docs |
versionId string | Project Version Id |
apihubUrl string | APIHUB Base URL. The default value for this parameter is ‘https://apihub.document360.io’ |
path string | File path of your respective API Reference |
force boolean | Force imports your API Reference. It will import even if there are errors or warnings present within your specification files. |
publish boolean | Publish articles after import. By default, all the articles will be in draft state after import |
With the ‘apidocs:resync’ command, you are able to update or resynchronize your API Definition.
d360 apidocs:resync --apiKey=c92e71ab-ebdf-4007-89ed-5d47493052cd --userId=3340e95e-2b68-4a3f-a8c9-124bcaec9972 --apiReferenceId=d486783f-b833-446e-aa71-615ac51392c3 --path=https://petstore.swagger.io/v2/swagger.json
Options | Description |
apiKey string | Project API Key |
userId string | User Id that’s used to generate API Reference |
apiReferenceId string | API Reference Id to resync |
apihubUrl string | APIHUB Base URL. The default value for this parameter is ‘https://apihub.document360.io’ |
path string | File path of your respective API Definitions |
force boolean | Force imports your API Reference. It will import even your spec files has errors and warnings |
publish boolean | Publish articles after import. By default, all the articles will be in draft state after import |
To sum up, I had a tremendous experience fostering this command line tool, which offers a compelling and effective method for importing and resyncing API definitions to Document360. Our team will constantly enhance this tool’s experience and stability.
An intuitive knowledge base software to easily add your content and integrate it with any application. Give Document360 a try!
GET STARTED