インターフェースドキュメントを別の場所にドッキングしているため、ドッキングドキュメントが必要です。比較してスワッガーを選択しましたが、スワッガーを使用したノードには落とし穴（詳細）が多く、特にドキュメントを表示するのに2日かかりました。コメント部分は、厳密にフォーマットに従って書く必要があります。
実装するswagger-jsdocとkoa2-swagger-uiを選択します。
まず、routesフォルダーにある別のファイルswagger.jsを起動しましょう。routesファイルの下にあるのはなぜですか。ドキュメントを他の人に見せると、127.0.0.130 / swagggerのようなURLが開かれるため、ノードのルートの1つに相当します。
依存関係をダウンロードする
npm install swagger-jsdoc koa2-swagger-ui
または
糸追加swagger-jsdockoa2-swagger-ui
バージョン
構成ドキュメント
//swagger.js
const router = require('koa-router')()
const swaggerJSDoc = require('swagger-jsdoc')
const swaggerDefinition = {
info: {
title: '你的文档标题',
version: '1.0.0',
description: '你的文档说明'
},
securityDefinitions: {
ApiKeyAuth: {
type: 'apiKey', // 类型
in: 'header', // 位置
name: 'token' // 参数
}
},
host: '127.0.0.1:300',//需要跟你node服务器地址一样
basePath: '/' // Base path (optional)
};
const options = {
swaggerDefinition,
apis: ['./routes/*.js'] // 写有注解的router的存放地址
};
const swaggerSpec = swaggerJSDoc(options)
// 通过路由获取生成的注解文件
router.get('/swagger.json', async function (ctx) {
ctx.set('Content-Type', 'application/json')
ctx.body = swaggerSpec
})
module.exports = router
app.jsファイルにルーティングをインポートします
//app.js
const koaSwagger = require('koa2-swagger-ui')
//swagger配置
app.use(//注意这里需要看koa2-swagger-ui的版本 不然会报koaSwagger不是一个函数等错误
koaSwagger({
routePrefix: '/swagger', // host at /swagger instead of default /docs
swaggerOptions: {
url: '/swagger.json' // example path to json
}
})
)
現時点では、ページは次のようになっています。
インターフェイスノート
インターフェイスのパスやパラメータなどの情報を127.0.0.1300/ swaggerページに表示する場合は、インターフェイスで注釈をネゴシエートする必要があります
。swaggerの注釈は、swaggerの識別を容易にするために@swaggerで始まります。管理者インターフェイスは以下の栗です。
//admin.js
// #region
// #region可以将注释代码收缩
/**
* @swagger
* /admin/userLogin:
* post:
* summary: 管理员登录
* description: 管理员登录
* tags:
* - 管理员模块
* parameters:
* - name: name
* in: query
* required: true
* description: 账号
* type: string
* - name: password
* in: query
* required: true
* description: 密码
* type: string
* responses:
* 200:
* description: 成功获取
* schema:
* type: 'object'
* properties:
* code:
* type: 'number'
* data:
* type: 'object'
* description: 返回数据
* message:
* type: 'string'
* description: 消息提示
*/
// #endregion
そのような比較的完全なインターフェース文書が出てきました。以下もページに表示されます。
このようにして、独自のインターフェイスドキュメントをページに出力できます。次のパートでは、フロントエンドが画像をアップロードして画像サーバーを表示するために要求する操作を紹介します。