Creating new articles is one of the actions you would often do in Document360. Creating and publishing an article with API allows you to automate the authoring process.
Basic requirements for creating an article
To create an article, you need the below values:
- Project version id
- Category id
- User id
In Document360, the order of categories and articles is based on the paths defined in the API specification files rather than tags. The first tag in the path determines the first category, with all endpoints mapped to that tag grouped accordingly.
Get Project version id
- Under Document360 Customer API, expand v2 > Project Versions.
- Click Gets list of project versions > Send.
This action will display all the versions available in the project. - Copy the desired project version id available next to the 'id' parameter and paste it into notepad or a preferred space.
Get Category id
- Under Project Versions, expand {project Version Id} and click Get the list of categories within project version.
- In the Params tab, you can find the Path Variables section.
- In the 'Value' field of projectVersionId, paste the project version id copied in step 3 and click Send.
This action will display all the categories in the desired version. - Copy the desired category id available next to the 'id' parameter and paste it into notepad or a preferred space.
Get User id
- Under v2, expand Teams and click Get all team accounts → Send
This action will display all the team accounts in the project. - Copy the desired user id available next to the 'id' parameter and paste it into notepad or a preferred space.
Creating an article
- Under v2, expand Articles and click Adds an article to an existing category.
- Navigate to the Body tab in the main window.
- You can find the below parameters:
- category_id - Paste the desired category id.
- project_version_id - Paste the desired project version id.
- title - Add the desired article title.
- user_id - Paste the desired user id.
- content - Add the desired article content.
- order - Specify the desired position of the article in the category. Enter the previous number of the desired position.
For example, If you want the new article to appear as the first in the category, enter the order parameter value as 0.
If you wish for the new article to appear as the fifth article in the category, enter the order parameter value as 4.
- Click Send.
- The new article is created successfully. You can verify this with the 200 OK status and success parameter value as true.
- Copy the article id available next to the 'id' parameter and paste it into notepad or a preferred space.
Publishing an article
To publish an article, you need the following values:
- Article id
- User id
Follow the below steps to publish an article:
- Under v2, expand Articles > {article Id} and click Publishes an article with an id.
- In the Params tab, you can find the Path variables section.
- In the 'Value' field of articleId, paste the desired article id.
- Navigate to the Body tab in the main window.
- You can find the below parameters:
- user_id - Paste the desired user id.
- version_number - Add the desired article version number.
- publish_message - Add the desired publish message for the article.
- Click Send.
- The desired article is published successfully. You can verify this with the 200 OK status and success parameter value as true.
FAQs
What steps can I take if an API endpoint appears in Swagger but not in Document360?
Start by verifying the reference file used for importing the API documentation. Ensure that the endpoint is included in the file and check for any missing parameters that could prevent it from rendering in Document360.
What common mistakes should I avoid when defining API endpoints?
Common mistakes include failing to define all required parameters, omitting examples, and using incorrect naming conventions. Ensure that every endpoint has a clear definition with all necessary elements included.