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.
Why do we need command line tools?
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:
-
- Automation: h2Command line tools allow developers to automate repetitive tasks or workflows, such as building and deploying code, running tests, and managing files and directories. By using command line tools, developers can write scripts that can perform these tasks automatically, saving them time and reducing the risk of errors.
- Flexibility: Command line tools provide a more flexible and customizable way to interact with the operating system compared to graphical user interfaces (GUIs). Developers can use a wide range of options, flags, and parameters to customize the behavior of command line tools to their specific needs.
- Remote access: Command line tools are often used for remote access to servers or cloud-based resources, allowing developers to manage and deploy code from anywhere with an internet connection.
- Speed: Command line tools are often faster and more efficient than GUIs because they don’t require graphical rendering and can perform tasks in the background. This can be especially important for developers working with large codebases or complex systems.
- Integration: Command line tools can easily be integrated with other tools and services, such as version control systems, testing frameworks, and deployment pipelines. This makes it easier for developers to create automated workflows and streamline their development process.
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.
d360 – Maintenance
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).
How to use d360 in CI/CD?
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
Commands available in d360
Currently, there are two commands available in our tool,
-
- apidocs – Import your API Definition to Document360
- apidocs:resync – Resync your API Definition to Document360
apidocs
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 |
apidocs:resync
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 |
Conclusion
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
–