Vue 使用typescript， 优雅的调用swagger API
<p>Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，后端集成下Swagger，然后就可以提供一个在线文档地址给前端同学。</p><p><img src="https://gitee.com/jadepeng/pic/raw/master/pic/2020/5/22/1590142373032.png" alt="swagger" loading="lazy"></p>
<p>前端如何优雅的调用呢？</p>
<h2 id="入门版">入门版</h2>
<p>根据文档，用axios自动来调用</p>
<pre><code class="language-javascript">// 应用管理相关接口
import axios from '../interceptors.js'
// 获取应用列表
export const getList = (data) => {
return axios({
url: '/app/list?sort=createdDate,desc',
method: 'get',
params: data
})
}
</code></pre>
<p>这里的问题是，有多少个接口，你就要编写多少个函数，且数据结构需要查看文档获取。</p>
<h2 id="进阶版本">进阶版本</h2>
<p>使用typescript，编写API，通过Type定义数据结构，进行约束。</p>
<p>问题： 还是需要手写</p>
<h2 id="优雅版本">优雅版本</h2>
<p>swagger 其实是一个json-schema描述文档，我们可以基于此，自动生成。</p>
<p>很早之前，写过一个插件 generator-swagger-2-t, 简单的实现了将swagger生成typescript api。</p>
<p>今天，笔者对这个做了升级，方便支持后端返回的泛型数据结构。</p>
<h3 id="安装">安装</h3>
<p>需要同时安装 Yeoman 和 -swagger-2-ts</p>
<pre><code class="language-bash">npm install -g generator-swagger-2-ts
</code></pre>
<p>然后cd到你的工作目录，执行:</p>
<pre><code class="language-bash">yo swagger-2-ts
</code></pre>
<p>按提示</p>
<ul>
<li>输入swagger-ui 地址，例如http://192.168.86.8:8051/swagger-ui.html</li>
<li>可选生成js 或者 typescript</li>
<li>可以自定义生成的api class名称、api文件名</li>
<li>API 支持泛型</li>
</ul>
<p>也可以通过命令行直接传递参数</p>
<pre><code class="language-bash"> yo swagger-2-ts --swaggerUrl=http://localhost:8080/swagger-ui.html --className=API --type=typescript --outputFile=api.ts
</code></pre>
<ul>
<li>swaggerUrl: swagger ui url swaggerui地址</li>
<li>className： API class name 类名</li>
<li>type： typescript or javascipt</li>
<li>outputFile: api 文件保存路径</li>
</ul>
<h3 id="生成代码demo">生成代码demo：</h3>
<pre><code class="language-javascript">
export type AccountUserInfo = {
disableTime?: string
isDisable?: number
lastLoginIp?: string
lastLoginPlace?: string
lastLoginTime?: string
openId?: string
}
export type BasePayloadResponse = {
data?: object
desc?: string
retcode?: string
}
/**
* User Account Controller
* @class UserAccountAPI
*/
export class UserAccountAPI {
/**
* changeUserState
* @method
* @name UserAccountAPI#changeUserState
* @paramaccountUserInfo - accountUserInfo
* @param $domain API域名,没有指定则使用构造函数指定的
*/
changeUserState(parameters: {
'accountUserInfo': AccountUserInfo,
$queryParameters?: any,
$domain?: string
}): Promise<AxiosResponse<BasePayloadResponse>> {
let config: AxiosRequestConfig = {
baseURL: parameters.$domain || this.$defaultDomain,
url: '/userAccount/changeUserState',
method: 'PUT'
}
config.headers = {}
config.params = {}
config.headers[ 'Accept' ] = '*/*'
config.headers[ 'Content-Type' ] = 'application/json'
config.data = parameters.accountUserInfo
return axios.request(config)
}
_UserAccountAPI: UserAccountAPI = null;
/**
* 获取 User Account Controller API
* return @class UserAccountAPI
*/
getUserAccountAPI(): UserAccountAPI {
if (!this._UserAccountAPI) {
this._UserAccountAPI = new UserAccountAPI(this.$defaultDomain)
}
return this._UserAccountAPI
}
}
/**
* 管理系统接口描述
* @class API
*/
export class API {
/**
*API构造函数
* @param domain API域名
*/
constructor(domain?: string) {
this.$defaultDomain = domain || 'http://localhost:8080'
}
}
</code></pre>
<h3 id="使用">使用</h3>
<pre><code class="language-javascript">import { API } from './http/api/manageApi'
// in main.ts
let api = new API("/api/")
api.getUserAccountAPI().changeUserState({
isDisable: 1
openId: 'open id'
})
</code></pre>
<h2 id="vue中最佳实践">Vue中最佳实践</h2>
<h3 id="maints-全局定义">main.ts 全局定义</h3>
<pre><code class="language-typescript">import { API } from './http/api/manageApi'
Vue.prototype.$manageApi = new API('/api/')
</code></pre>
<h3 id="增加dts">增加.d.ts</h3>
<p>增加types文件，方便使用智能提示</p>
<pre><code class="language-typescript">import { API } from '@/http/api/manageApi'
import { MarkAPI } from '@/http/api/mark-center-api'
declare module "vue/types/vue" {
interface Vue {
$manageApi: API
$markApi: MarkAPI
}
}
</code></pre>
<h3 id="实际使用">实际使用</h3>
<p>现在可以在vue里直接调用了。</p>
<p><img src="https://gitee.com/jadepeng/pic/raw/master/pic/2020/5/22/1590143121653.png" alt="vscode调用" loading="lazy"></p>
<pre><code class="language-javascript">this.$manageApi
.getUserAccountAPI().changeUserState({isDisable: 1， openId: 'open id'})
</code></pre>
<h2 id="开源地址">开源地址</h2>
<p>https://github.com/jadepeng/generator-swagger-2-ts</p>
<p>欢迎star！</p>
<hr>
<blockquote>
<p>作者：Jadepeng<br>
出处：jqpeng的技术记事本--http://www.cnblogs.com/xiaoqi<br>
您的支持是对博主最大的鼓励，感谢您的认真阅读。<br>
本文版权归作者所有，欢迎转载，但未经作者同意必须保留此段声明，且在文章页面明显位置给出原文连接，否则保留追究法律责任的权利。</p>
</blockquote>
</div>
<div id="MySignature" role="contentinfo"><br><br>
来源：https://www.cnblogs.com/xiaoqi/p/generator-swagger-2-ts-2.html
頁:
[1]