How to make beautiful documentation for the Web API, for which it will not be a shame
I would like to tell you about the utility with which you can forget about the pain of creating documentation for the Web API. About how to do this, I ask everyone under cat.
So, welcome under the cat, {username}! You might ask with what makes it so beautiful? Answer: apiDoc. What is apiDoc? apiDoc is a utility for generating documentation based on comments in the code. But with one qualification, these comments must be of a certain kind. You can create documentation for projects in: C #, Dart, Erlang, Go, Java, Javascript, PHP, Python, Ruby, Perl, and others. But in this article I will explain how to make such beautiful documentation based on a Python project.
For this you will need:
')
Those who have the Node.js package installed, skip this step, but make sure that npm is working for you. And the rest should download the installer from the sitejsorg site and install it. Make sure Node.js is in the $ PATH variable. Example installer for Mac OS X:
I hope everyone coped with the installation of Node.JS and we can proceed further. To install apiDoc, open a terminal (command line in Windows) and run the command:
And at the exit you should get something like this.
Well, we got to the creation of documentation. In order to generate the documentation you need to make comments in the code. Here is an example of a comment in the code.
What is what? I will give a description of some basic “tags” for generating documentation. All tags can be found here .
Required tag for generating documentation.
Tag identifies the name of the block of documentation. It is recommended to always use.
Tag linking blocks of documentation in one group on the documentation website.
The tag is used to determine the version of the method.
The tag is used to describe the parameter passed to the method.
So, after a brief introduction to the apiDoc tags, you can try to create documentation, for this you need to prepare a field of action. To do this, put the apidoc.json configuration file in the root.
Next, to generate, run the command:
At the exit you will get this:
Documentation can be picked up in the doc folder which lies in the root of your project. To see the result, open index.html.
We managed to make practical and beautiful documentation. Here's what she looks like:
You can see how it looks completely and click on the buttons here .
So, welcome under the cat, {username}! You might ask with what makes it so beautiful? Answer: apiDoc. What is apiDoc? apiDoc is a utility for generating documentation based on comments in the code. But with one qualification, these comments must be of a certain kind. You can create documentation for projects in: C #, Dart, Erlang, Go, Java, Javascript, PHP, Python, Ruby, Perl, and others. But in this article I will explain how to make such beautiful documentation based on a Python project.
For this you will need:
')
- Node.js (with npm)
- Project to be documented
- Some free time
Installing Node.js
Those who have the Node.js package installed, skip this step, but make sure that npm is working for you. And the rest should download the installer from the sitejsorg site and install it. Make sure Node.js is in the $ PATH variable. Example installer for Mac OS X:
Install apiDoc
I hope everyone coped with the installation of Node.JS and we can proceed further. To install apiDoc, open a terminal (command line in Windows) and run the command:
sudo npm install -g apidoc And at the exit you should get something like this.
Preparation for the creation of documentation
Well, we got to the creation of documentation. In order to generate the documentation you need to make comments in the code. Here is an example of a comment in the code.
""" @api {get} /2/get_news?offset=:offset&count=:count @apiName GetNews @apiGroup News @apiVersion 0.2.0 @apiParam {String} [count=5] @apiParam {String} [offset=0] - """ What is what? I will give a description of some basic “tags” for generating documentation. All tags can be found here .
@api
Required tag for generating documentation.
Using
method - request type (GET, POST, PUT, etc.)
path - the path to the method, for example / 2 / get_news
title - the name of the method that will be displayed in the documentation
@api {method} path [title] method - request type (GET, POST, PUT, etc.)
path - the path to the method, for example / 2 / get_news
title - the name of the method that will be displayed in the documentation
Usage example:
""" @api {get} /user/:id """ @apiName
Tag identifies the name of the block of documentation. It is recommended to always use.
Using
name - the name of the method
@apiName name name - the name of the method
Usage example:
""" @apiName GetNews """ @apiGroup
Tag linking blocks of documentation in one group on the documentation website.
Using
name - group name
@apiGroup name name - group name
Usage example:
""" @apiGroup News """ @apiVersion
The tag is used to determine the version of the method.
Result of versioning:
Using
version - the version of the method according to semantic versioning is in more detail here .
@apiVersion version version - the version of the method according to semantic versioning is in more detail here .
Usage example:
""" @apiVersion 0.2.0 """ @apiSuccess
The tag is used to describe the parameter passed to the method.
Using
type - object type ({Boolean}, {Number}, {String}, {Object}, {String []} and others)
field - the name of the object to be received after the request
description - description of this object
@apiSuccess [{type}] field [description] type - object type ({Boolean}, {Number}, {String}, {Object}, {String []} and others)
field - the name of the object to be received after the request
description - description of this object
Usage example:
""" @api {get} /user/:id @apiSuccess {String} firstname Firstname of the User. @apiSuccess {String} lastname Lastname of the User. """ Documentation production
So, after a brief introduction to the apiDoc tags, you can try to create documentation, for this you need to prepare a field of action. To do this, put the apidoc.json configuration file in the root.
Example acidoc.json
{ "name": " ", // "version": "0.2.0", // API( ) "description": " - ", // "title": " API ", // API "url" : "https://api.mynstu.me", // Web API "sampleUrl": "https://api.mynstu.me", // Web API "template": { // "withCompare": true, // "withGenerator": true // apiDoc } } Next, to generate, run the command:
apidoc At the exit you will get this:
Documentation can be picked up in the doc folder which lies in the root of your project. To see the result, open index.html.
Results
We managed to make practical and beautiful documentation. Here's what she looks like:
You can see how it looks completely and click on the buttons here .
Source: https://habr.com/ru/post/262813/
All Articles