Apidoc writing background documents

Time:2021-6-13

brief introduction

In the background of developmentapiIn this way, we need to provide the necessary information to the developers of web and mobile clientsapiDocument, let’s introduce it today

A document writing toolapidocjsThe whole grammar still followsmarkdownThe grammar of

of courseapidocsupportGrunt, home pagehttps://github.com/apidoc/grunt-apidoc

In fact, there are many similar tools, but the only purpose is to provide better instructions for other developers. Therefore, document writing and specification are very important

install

Global installation on the command line

$ npm install apidoc -g

apidocsupportGrunt, home pagehttps://github.com/apidoc/grunt-apidoc

Can be used in a projectnpm install grunt-apidoc --save-devinstall

add togrunt.loadNpmTasks('grunt-apidoc')reachGruntfile.js

add togrunt taskThis contains the output directory and other information

apidoc: {
      myapp: {
        src: "app/",
        dest: "apidoc/"
      }
}
module.exports = function(grunt) {
    grunt.config.set('clean', {
      apidoc: {
        myapp: {
          src: "app/",
          dest: "apidoc/"
        }
      }
    });
    grunt.loadNpmTasks('grunt-apidoc');
};

After installation, you can check the command

$ apidoc -h

We will see some parameters below. Here are a few

title address
-o Specifies the output directory of the document
-i The input folder contains
-t Specifies the template for the output file
-c Specifies the file directory for the configuration file

Next comes the configuration fileappidoc.jsonAn example of the definition of is as follows

{
  "name" : "codespace",
  "version": "1.0.0",
  "title": "codespace",
  "description": test project"
}

Of course, the content of the configuration file is put in thepackage.jsonIt’s OK (the same fields are the same aspackage.jsonThe same and the different are placed in the same placeapidoc(2)

For example, it is running on the terminal

$ npm init

Fill in your project information and don’t forget to add itapidocThis configuration item

{
  "name": "codespace",
  "version": "1.0.0",
  "description": "test for codespace",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "api"
  ],
  "author": "jellybean",
  "license": "MIT",
  "apidoc":{
    "title":"codespace"
  }
}

Of course, in order to generate the final document file, we also need to generate our code file. Of course, in the actual project, we can create a new document file

We are heremyappCreate a new generation in the file directorydoc.phpThe details are as follows (the syntax and format of the document will be introduced later)

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 *
 * @apiSuccessExample Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

comemyappOf course, you can also see the specific commands in the current directory

$  apidoc -i myapp/ -o apidoc/

This will be generated in the current directoryapidocThe file directory contains the style and content of the final document. In this way, we can deploy the document directly to the server
Or some hosting platforms

Case rendering
Apidoc writing background documents

For the syntax of the document, of course, the specific is to seeOfficial documentsHere are a few

First, the code block of the document is based on/**and*/The beginning and the end can be seen from the above examples

@api

Define the form and address of the interface, including the specific request type and parameters

@api {method} path [title]

@apiName

Define interface name

@apiGroup

Define the group to which the interface belongs, because interfaces may be classified, such as book interfaces and comment interfaces

@apiDefine

Define a set of interfaces to return instances, and@apiUseYou can interpret it as declaring afunction)

Then use it where you need it. For example, we now define a set of error prompts

/**
 * @apiDefine UserNotFoundError
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

In this way, we may use a bad interface and fail to find the user. This error can be added when it returns

@apiUse UserNotFoundError

@apiHeader

Defines the header information of the interface request, such as

/**
 * @api {get} /user/:id
 * @apiHeader {String} access-key Users unique access-key.
 */

@apiParam

The request parameter of the interface lists whether the request parameter type of the interface is optional[]Contains the parameter name, such as

@apiParam {Number} id Users unique ID.
@apiParam {String} [firstname] Firstname of the User.

@apiSuccess

The field information returned by the interface successfully includes the description of the interface type

@apiSuccess {String} firstname Firstname of the User.
@apiSuccess {String} lastname  Lastname of the User.

@apiSuccessExample Success-Response:

The formal examples of successful return of interface request are as follows

HTTP/1.1 200 OK
      {
        "firstname": "John",
        "lastname": "Doe"
      }

@apiError

The error message that defines the interface contains the error type and description

@apiErrorExample Error-Response:

Define an interface error and return an instance, such as

HTTP/1.1 404 Not Found
      {
        "error": "UserNotFound"
      }