vue编写的功能强大的swagger-ui页面及使用方式

1. 什么是Swagger-UI页面？

Swagger UI是一个通过注解的方式为 RESTful API 描述文档生成在线文档界面的工具。通过Swagger UI，我们可以详细地查看到API接口的信息，包括接口名称、接口描述、请求地址、请求方式、参数类型、参数描述、响应状态码等等。Swagger UI可以很方便地帮助我们对API接口进行测试与调试。

1. 如何使用Vue来编写Swagger-UI页面？

首先，我们需要安装swagger-ui-dist、swagger-client、vue-router、vuex四个插件，其中：

• swagger-ui-dist：用于加载Swagger UI页面；
• swagger-client：用于与Swagger提供的API接口进行交互，获取API数据；
• vue-router：实现Vue中的路由功能；
• vuex：实现Vue中的状态管理。

下面是在Vue项目中的安装方法：

npm install swagger-ui-dist swagger-client vue-router vuex --save

接下来，我们需要编写两个组件，分别是SwaggerUI和SwaggerUIWrapper：

• SwaggerUI组件：负责渲染Swagger UI界面；
• SwaggerUIWrapper组件：负责加载Swagger UI数据，并将数据传递给Swagger UI组件。

下面是SwaggerUI组件的代码：

<template>
  <div ref="swagger-ui"></div>
</template>

<script>
import SwaggerUI from 'swagger-ui-dist'
import 'swagger-ui-dist/swagger-ui.css'

export default {
  name: 'SwaggerUI',
  props: {
    url: {
      type: String,
      default: '/swagger.json'
    },
    title: {
      type: String,
      default: 'Swagger UI'
    }
  },
  mounted () {
    SwaggerUI({
      dom_id: this.$refs['swagger-ui'],
      url: this.url,
      docExpansion: 'none',
      defaultModelsExpandDepth: 0,
      presets: [SwaggerUI.presets.apis],
      plugins: [SwaggerUI.plugins.DownloadUrl],
      layout: 'StandaloneLayout',
      deepLinking: true,
      validatorUrl: null,
      displayOperationId: false,
      displayRequestDuration: false
    })
  }
}
</script>

下面是SwaggerUIWrapper组件的代码：

<template>
  <div>
    <router-view :swagger-data="swaggerData"></router-view>
  </div>
</template>

<script>
import SwaggerClient from 'swagger-client'
import { mapState } from 'vuex'

export default {
  name: 'SwaggerUIWrapper',
  computed: {
    ...mapState(['swaggerData'])
  },
  async created () {
    const swaggerClient = await SwaggerClient(this.$store.state.swaggerConfig)
    this.$store.commit('setSwaggerData', swaggerClient.spec)
  }
}
</script>

其中，setSwaggerData和swaggerConfig方法需要放到Vuex的store中，下面是store中的代码：

import Vue from 'vue'
import Vuex from 'vuex'

Vue.use(Vuex)

export default new Vuex.Store({
  state: {
    swaggerData: null,
    swaggerConfig: {
      url: '/swagger.json'
    }
  },
  mutations: {
    setSwaggerData (state, swaggerData) {
      state.swaggerData = swaggerData
    }
  }
})

最后，我们需要配置路由，将SwaggerUIWrapper组件映射到路由路径中：

import Vue from 'vue'
import Router from 'vue-router'
import SwaggerUIWrapper from '@/components/SwaggerUIWrapper.vue'

Vue.use(Router)

export default new Router({
  routes: [
    {
      path: '/',
      name: 'SwaggerUIWrapper',
      component: SwaggerUIWrapper
    }
  ]
})

1. 如何使用Vue编写Swagger-UI页面的示例？

下面是一个简单的示例：

• 在Vue项目中创建一个名为“Swagger-UI”的组件；
• 使用上面提到的代码，在SwaggerUI组件和SwaggerUIWrapper组件中加载Swagger UI页面；
• 配置路由，将Swagger-UI组件映射到路由路径中；
• 在Swagger UI中加载一个API数据，例如http://petstore.swagger.io/v2/swagger.json。

下面是代码示例：

<template>
  <div>
    <SwaggerUI title="My Swagger UI" :url="swaggerDataUrl" />
  </div>
</template>

<script>
import SwaggerUI from '@/components/SwaggerUI.vue'

const swaggerDataUrl = 'http://petstore.swagger.io/v2/swagger.json'

export default {
  name: 'Swagger-UI',
  data () {
    return {
      swaggerDataUrl
    }
  },
  components: {
    SwaggerUI
  }
}
</script>

import Vue from 'vue'
import Router from 'vue-router'
import SwaggerUI from '@/components/Swagger-UI.vue'

Vue.use(Router)

export default new Router({
  routes: [
    {
      path: '/',
      name: 'Swagger-UI',
      component: SwaggerUI
    }
  ]
})

1. 另一个使用Vue编写Swagger-UI页面的示例：

下面是一个更加复杂的示例，其中使用了路由参数，根据不同的路径加载不同的API数据：

• 在Vue项目中创建一个名为“Swagger-UI”的组件；
• 在SwaggerUIWrapper组件中根据路由参数动态加载API数据；
• 配置路由，使用路由参数来传递API数据的地址；
• 在Swagger UI中加载不同的API数据。

下面是代码示例：

<template>
  <div>
    <SwaggerUI title="My Swagger UI" :url="swaggerDataUrl" />
  </div>
</template>

<script>
import SwaggerUI from '@/components/SwaggerUI.vue'

export default {
  name: 'Swagger-UI',
  components: {
    SwaggerUI
  },
  computed: {
    swaggerDataUrl () {
      return this.$route.params.swaggerDataUrl
    }
  }
}
</script>

<template>
  <div>
    <router-view :swagger-data-url="swaggerDataUrl"></router-view>
  </div>
</template>

<script>
import SwaggerClient from 'swagger-client'
import { mapState } from 'vuex'

export default {
  name: 'SwaggerUIWrapper',
  computed: {
    ...mapState(['swaggerData']),
    swaggerDataUrl () {
      return this.$route.params.swaggerDataUrl
    }
  },
  async created () {
    const swaggerClient = await SwaggerClient({
      url: this.swaggerDataUrl
    })
    this.$store.commit('setSwaggerData', swaggerClient.spec)
  }
}
</script>

import Vue from 'vue'
import Router from 'vue-router'
import SwaggerUIWrapper from '@/components/SwaggerUIWrapper.vue'

Vue.use(Router)

export default new Router({
  routes: [
    {
      path: '/',
      name: 'Swagger-UI',
      component: SwaggerUIWrapper,
      children: [
        {
          path: ':swaggerDataUrl',
          name: 'Swagger-UI-Child',
          component: () => import('@/views/Swagger-UI.vue')
        }
      ]
    }
  ]
})

在路由路径中添加了一个动态参数swaggerDataUrl，如：http://localhost:3000/https://petstore.swagger.io/v2/swagger.json，就可以动态加载数据了。