接口文档
框架提供了文档自动生成功能,减少了维护接口文档的工作量。
介绍
框架采用Swagger 2.0,配合Joi校验规则来生成文档。
swagger配置只能出现在公共模块中。
我们先来看一个示例配置:
// common/config/default.js
module.exports = {
swagger: {
enable: true,
apiJson: '/api-json',
apiDocs: '/api-docs',
html: `
<!DOCTYPE html>
<html>
<head>
<title>Documents</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<redoc spec-url='./api-json'></redoc>
<script src="https://storage.360buyimg.com/o2static/redoc.min.js"> </script>
</body>
</html>`,
spec: {
info: {
title: 'API',
description: 'For api.',
version: '1.0.0'
},
tags: [
{
name: 'Demo',
description: 'For demo.'
}
]
}
}
}
配置说明
enable
:是否开启swagger文档,默认根据是否为生产环境来设置apiJson
:文档JSON地址,默认为/api-json
apiDocs
:文档地址,默认为/api-docs
html
:文档渲染html,默认为reDocspec
:swagger 选项spec.info
:object, 必须,需要提供至少title,description,version字段,还可以提供contact、license字段,同Swagger info字段spec.host
:string,可选,文档host地址spec.tags
:Array,可选,item必须包含name和description字段,接口标签,用于整理接口分类
const { Behavior } = require('salak')
class User extends Behavior {
actionIndex () {
return {
meta: {
summary: '',
description: '',
tags: ['User'] // ref to spec.tags name
}
}
}
}
module.exports = User
文档访问
文档地址默认为:http://host/api-docs
文档swagger json地址默认为:http://host/api-json
框架在启动时,会将项目的swagger json生成到 runtime/swagger/swagger.json
中,可以从该位置获取文档信息。