015-ant design pro advanced use API documentation tool

I. Overview

Original address: https://pro.ant.design/docs/api-doc-cn

In daily development, the front and back ends are often separated. At this time, a set of interface standards is agreed, and the front and back ends are independently developed, so that they will not be blocked by the technical difficulties of the other party, thus ensuring the progress of the project.

In Ant Design Pro, we already have a relatively complete mock function, and the  roadhog-api-doc  tool can read the interface information from the mock data of the project to generate the corresponding document, so that it can be displayed more clearly and clearly The interface of the project.

The effect is as follows: Pro API Docs .

2. Details

2.1. How to use

npm install roadhog-api-doc -g

2,1.1, local service

Go to the project root directory and run:

roadhog-api-doc start [port]

You can run a document website in the current project, but the premise is that it must be a roadhog -based project like Ant Design Pro   , and use the data mock function, because the source of information for the document is the mock file.

It should be noted that the above  port parameters refer to  roadhog the service from the current local application. If it is specified, you can directly click to access the project interface locally. If it is not specified, the network request will be static.

2.1.2. Static site generation

Project root directory, run:

roadhog-api-doc build

Three document site static files will be generated: api.html, api.js, api.css, which you can deploy to your own site for online access, where the data has been static (converting network requests into code data).

2.1.3. Writing documents

Generally speaking, you can generate documentation without adding any additional dependencies, but if you need to describe the interface, you need to  roadhog mock modify the file in the following format:

npm install roadhog-api-doc --save-dev # Install roadhog-api-doc as a local tool dependency

import { format } from 'roadhog-api-doc';

const proxy = {
  'GET /api/currentUser': {
    $desc: "Get the current user interface" ,
    $params: {
      pageSize: {
        desc: 'page break' ,
        exp: 2,
      },
    },
    $body: {
      name: 'momo.zxy' ,
      avatar: imgMap.user,
      userid: '00000001',
      notifyCount: 12,
    },
  },
};

export default format(proxy);

in:

• $desc: interface description

• $params: interface parameter description, the object describes the meaning of each parameter

• $body: data return result, usually mock data

　　

2.1.4. Local test mock data and real port

After launching the local API Docs site, you can click the  send button to send  POST or  GET request, and the return value will be displayed in the pop-up box:

　　

It should be noted that if the port number is not added when the API Docs site is started, the returned data here is static data. If the port number is added and the project is also run locally at the same time, the actual data will be returned directly.

If you want to directly access the real data online, you need to rewrite the current project  .roadhog.mock.jsand redirect to the online path.

 Learn more by visiting  the roadhog-api-doc github .