Feature: Document generator

[oscar60310]

Description

Generate OAS document for our restful API.

Demo

openapi: 3.0.3
info:
  title: An API schema for testing
  version: 1.2.3
  description: Some description with **markdown** supported.
paths:
  /user/{id}:
    get:
      description: Get user information
      responses:
        '200':
          description: The default response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    description: The unique-id of the user
                    type: string
                  username:
                    description: The username of the user
                    type: string
                  age:
                    description: The age of the user
                    type: number
                  groups:
                    description: The groups that the user has joined
                    type: object
                    properties:
                      id:
                        description: The unique-id of the group
                        type: string
                      groupName:
                        description: The groupName of the group
                        type: string
                      public:
                        description: Whether the group was public
                        type: boolean
                    required:
                      - id
                      - groupName
                required:
                  - id
                  - username
            text/csv:
              schema:
                type: string
        '400':
          description: Client error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
              examples:
                USER_NOT_FOUND:
                  description: We can't find any user with the provided id
                  value:
                    code: USER_NOT_FOUND
                    message: We can't find any user with the provided id
                AGENT_NOT_ALLOW:
                  description: The agent is not allow
                  value:
                    code: AGENT_NOT_ALLOW
                    message: The agent is not allow
        5XX:
          description: Server error
      parameters:
        - name: id
          in: path
          schema:
            type: string
            minLength: 3
            maxLength: 10
            pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
          required: true
        - name: agent
          in: header
          schema:
            type: number
            minimum: 10
            maximum: 15
          required: false
        - name: force
          in: query
          schema:
            type: boolean
          required: false
        - name: username
          in: query
          schema:
            type: string
            enum:
              - ivan
              - eason
              - freda
          required: false
  /user/{id}/order/{oid}:
    get:
      responses:
        '200':
          description: The default response
          content:
            application/json:
              schema:
                type: object
                properties: {}
            text/csv:
              schema:
                type: string
        5XX:
          description: Server error
      parameters:
        - name: id
          in: path
          schema:
            type: string
          required: true
        - name: oid
          in: path
          schema:
            type: string
          required: true
  /users:
    get:
      responses:
        '200':
          description: The default response
          content:
            application/json:
              schema:
                type: object
                properties: {}
            text/csv:
              schema:
                type: string
        5XX:
          description: Server error
      parameters: []

We extract these values for the schema to document:

1. Project config
   • Version
   • Name
   • Description
2. API information
   • URL
   • Description
   • Error codes
3. Parameters
   • Type
   • Description
   • Validators
   • Name
4. Response
   • Name
   • Type
   • Description

About Validators' Constraints

For generating documents, we need to know what the validator do inside validateData function, so I add a method getConstraints to the validator interface, it should tell us what it does with some standard rules:

export class StringValidator implements IValidator {
  public name = 'StringValidator';
  public validateSchema(args: any): boolean {
    return true;
  }
  public validateData(data: string, args: any): boolean {
    if (data.length > args.maxLength || data.length < args.minLength)
      return false;
    return true;
  }
  public getConstraints(args: any) {
    return [
      Constraint.MaxLength(args.maxLength),
      Constraint.MinLength(args.minLength),
    ];
  }
}

According to Meeting #8
Instead of hard-cord constraints in this function, we can use some transform libraries like joi-to-json-schema. But I think we can do it later after previous PRs merged.

Duplicated codes

d61b0d2 is a duplicated commit from previous PR, it'll be removed after rebased.

Snapshots

Document generated by redoc

[kokokuo]

Beside one question, other LGTM 👍 👍

[kokokuo]

Does here miss the assert behavior, not see the expect checker, e.g: expect(xxxx).not.toThrow() for not throwing error?

[oscar60310]

Sure, added it.

[oscar60310]

Hi @kokokuo , I've fixed all issues.