Umi从零搭建Ant Design Pro项目（3）集成 openapi 插件

1. 安装插件

pnpm add @umijs/max-plugin-openapi
pnpm add swagger-ui-dist

如果不安装swagger-ui-dist，不会影响运行。但会报错。

2.配置文件

 export default defineConfig({
   // umi插件配置
   plugins: ['@umijs/max-plugin-openapi'],
   // openAPI配置
   openAPI: {
     requestLibPath: "import { request } from '@umijs/max';",
     mock: false,
     schemaPath: path.resolve(__dirname, 'swagger.json'),
   },

3.关于

注意sagger.json是本地生成的关于api的json。

可以使用apifox编辑好接口后，直接生成。

格式类似

{
  "info": {
    "title": "q",
    "description": "",
    "version": "1.0.0"
  },
  "tags": [
    {
      "name": "组卷管理"
    }
  ],
  "paths": {
    "/papers/search": {
      "get": {
        "summary": "根据条件查询已有组卷",
        "deprecated": false,
        "description": "查询已有组卷",
        "operationId": "searchPapers",
        "tags": [
          "组卷管理"
        ],
        "parameters": [
          {
            "name": "paper",
            "in": "query",
            "description": "组卷名称",
            "required": false,
            "type": "string"
          },
          {
            "name": "grade",
            "in": "query",
            "description": "年级",
            "required": false,
            "type": "string"
          },
          {
            "name": "subject",
            "in": "query",
            "description": "学科",
            "required": false,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "查询成功",
            "headers": {},
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/Paper"
              }
            }
          },
          "400": {
            "description": "参数错误",
            "headers": {},
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          },
          "500": {
            "description": "服务器内部错误",
            "headers": {},
            "schema": {
              "$ref": "#/definitions/ErrorResponse"
            }
          }
        },
        "security": [],
        "produces": [
          "application/json"
        ]
      }
    }
  },
  "security": [],
  "swagger": "2.0",
  "definitions": {
    "Paper": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64",
          "description": "组卷ID"
        },
        "name": {
          "type": "string",
          "description": "组卷名称"
        },
        "status": {
          "type": "integer",
          "description": "组卷状态：0-正在组卷，1-已完成组卷"
        }
      },
      "required": [
        "id",
        "name",
        "status"
      ]
    },
    "ErrorResponse": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ]
    }
  },
  "securityDefinitions": {},
  "x-components": {}
}

4. 修改package 【重要】

一定看这里，在package.json里加上name与version。不然会一直报错，无法运行。

 {
   "name": "name",
   "version": "0.0.1",
   ...
   "scripts": {
   	...
     "openapi": "max openapi"
   },
   "dependencies": {
   	...
   },
   "devDependencies": {
   	...
   }
 }

5.运行

pnpm openapi

应该会servers目录生成pageage.json中填写的name值目录且生成相关文件。

关于swagger-ui

前面如安装了swagger-ui-dist,那就可以在运行pnpm start，可访问/umi/plugin/openapi查看接口。个人感觉如何使用apifox等工具后，查看不查看的没有什么用。