# dubbo-swagger

> the dubbo swagger(OpenAPI) integration, aims to act as the dubbo HTTP gateway and document server

Latest version **1.0.1** (published 2018-10-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install dubbo-swagger
pnpm add dubbo-swagger
yarn add dubbo-swagger
bun add dubbo-swagger
```

Provides the command `oas-flush`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2018-10-31 |
| First published | 2018-10-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 11 |
| Unpacked size | 25.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | James ZHANG |
| Maintainers | thenorthmemory |
| Keywords | dubbo, swagger, node-dubbo, swagger-ui, OpenAPI, yaml |

## Links

- npm: https://www.npmjs.com/package/dubbo-swagger
- Repository: https://github.com/TheNorthMemory/dubbo-swagger
- Homepage: https://github.com/TheNorthMemory/dubbo-swagger#readme
- Issues: https://github.com/TheNorthMemory/dubbo-swagger/issues
- npm.io page: https://npm.io/package/dubbo-swagger

## Dependencies (11)

- [koa](https://npm.io/package/koa.md) ^2.6.1
- [debug](https://npm.io/package/debug.md) ^4.1.0
- [dubbo](https://npm.io/package/dubbo.md) ^1.1.1
- [lodash](https://npm.io/package/lodash.md) ^4.17.11
- [js-yaml](https://npm.io/package/js-yaml.md) ^3.12.0
- [hessian.js](https://npm.io/package/hessian.js.md) ^2.8.1
- [js-to-java](https://npm.io/package/js-to-java.md) ^2.6.0
- [koa-static](https://npm.io/package/koa-static.md) ^5.0.0
- [koa-path-match](https://npm.io/package/koa-path-match.md) ^2.0.0
- [koa-better-body](https://npm.io/package/koa-better-body.md) ^3.0.4
- [node-zookeeper-client](https://npm.io/package/node-zookeeper-client.md) ^0.2.2

## Recent versions

- 1.0.1 (latest) — 2018-10-31

## README

# DUBBO SWAGGER

[![NPM version](https://badge.fury.io/js/dubbo-swagger.svg)](http://badge.fury.io/js/dubbo-swagger)
[![npm module downloads per month](http://img.shields.io/npm/dm/dubbo-swagger.svg)](https://www.npmjs.org/package/dubbo-swagger)

[English Version](README_en-US.md)

得益于开源项目 [OpenAPI-Specification](https://github.com/OAI/OpenAPI-Specification) 及 [node-dubbo](https://www.npmjs.com/package/dubbo)，使用纯JavaScript远程消费 [DUBBO](https://dubbo.io) 服务。

## 项目结构

```
├── api
│   ├── any_validFolder-com.foo.interface
│   │   ├── complex.yaml
│   │   ├── minus.yaml
│   │   ├── plus.yaml
│   │   └── meta.json
├── bin
│   └── flush.js
├── index.js
├── lib
│   ├── consumer.js
│   └── descriptor.js
├── package.json
└── static
    ├── index.html
    ├── swagger.json
    └── swagger.yaml
```

## 环境变量

- `process.env.ZKADDR`

  > zookeeper 注册中心地址，如未设置，http服务仅能当作接口文档，无法发起有效RPC调用

- `process.env.PORT || 3030`

  > koa http server 监听端口

- `process.env.CLUSTERNUM || 1`

  > nodejs cluster 进程数目，windows 平台默认为1，*nix 平台默认为 CPU 核数

- `process.env.OAI_EXT_FLAT || 'x-flat'`

  > OAS 扩展key，声明入参是扁平入参

- `process.env.OAI_EXT_OBJECT || 'x-object'`

  > OAS 扩展key，声明入参(有且只有1个入参)是对象入参

- `process.env.OAI_EXT_MAP_KEY || 'x-key'`

  > OAS 扩展key，声明入参如果是Map对象，map-key的数据类型描述

- `process.env.OAI_ARRAY_COLLECTION || ','`

  > OAS 默认array类型分隔符

- `process.env.APPHOST || 'dubbo.io'`

  > `bin/flush.js` 生成文档时的默认主机地址

- `process.env.NO_WRITE`

  > 如设置此变量，`bin/flush.js` 仅校验yaml语法是否正确，不写入最终 `static/swagger.*`

## `bin/flush.js`

作用是把目录 `api/*/*.yaml` 文件组合生成为 `static/swagger.*` 文件

## `lib/consumer.js`

dubbo consumer wrapper

### `lib/descriptor.js`

入参转换核心部件，把 HTTP POST (`ctx.request.fields`) 转换成 [hessian.js](https://www.npmjs.com/package/hessian.js) 入参

### `index.js`

HTTP 入口，路由监听 `/providers/:serviceName/:serviceMethod` 消费 DUBBO RPC 服务

### `static/index.html`

swagger-ui 入口

## `api/*/meta.json`
- interface
- timeout
- group
- version
- tags
  > 扩展的 swagger UI 标签，Array[String] 结构

## 基础OAS数据结构与 [js-to-java](https://www.npmjs.com/package/js-to-java) 类型映射

```json
    'boolean'                : java.Boolean,
    'string'                 : java.String,
    'string_byte'            : java.Byte,
    'string_date'            : java.Date,
    'string_date-time'       : java.Date,
    'number'                 : java.int,
    'number_float'           : java.Float,
    'number_double'          : java.Double,
    'integer'                : java.Integer,
    'integer_int64'          : java.Long,

    'object_map'             : java.Map,

    'array_boolean'          : java.array.Boolean,
    'array_string'           : java.array.String,
    'array_string_byte'      : java.array.Byte,
    'array_string_date'      : java.array.Date,
    'array_string_date-time' : java.array.Date,
    'array_number'           : java.array.int,
    'array_number_float'     : java.array.Float,
    'array_number_double'    : java.array.Double,
    'array_integer'          : java.array.Integer,
    'array_integer_int64'    : java.array.Long,
```

## 示例

api/any_validFolder-com.foo.interface/meta.json

```json
{
    "interface": "com.foo.interface",
    "timeout": 100,
    "tags": [
        "Math测试"
    ]
}
```

api/any_validFolder-com.foo.interface/plus.yaml

```yaml
summary: 'a+b=?'
x-object: com.foo.rpc.plus
parameters:
  - name: a
    in: formData
    type: integer
    format: int32
  - name: b
    in: formData
    type: integer
    format: int32
responses:
  '200':
    description: ''
```

api/any_validFolder-com.foo.interface/minus.yaml


```yaml
summary: 'a-b=?'
x-flat: true
parameters:
  - name: a
    in: formData
    type: integer
    format: int32
  - name: b
    in: formData
    type: integer
    format: int32
responses:
  '200':
    description: ''
```

api/any_validFolder-com.foo.interface/complex.yaml

```yaml
summary: 'complex request'
x-object: com.foo.rpc.complex
parameters:
  - name: a
    in: formData
    type: integer
    format: int64
    required: true
  - name: b
    in: formData
    type: string
    required: true
  - name: c
    in: formData
    type: array
    items:
      type: string
  - name: d
    in: formData
    type: object
    additionalProperties:
      x-key:
        type: string
      type: string
  - name: e
    in: formData
    type: array
    items:
      type: integer
      format: int64
  - name: f
    type: number
    nullable: true
    format: double
  - name: g
    nullable: true
    type: integer
  - name: h
    nullable: true
    type: number
    format: float
  - name: i
    in: formData
    nullable: true
    type: array
    items:
      type: object
      x-object: io.dubbo.model.one
      properties:
        J:
          type: integer
          format: int64
        K:
          type: string
        L:
          type: array
          items:
            type: string
        M:
          type: object
          x-object: io.dubbo.model.two
          properties:
            N:
              type: string
            O:
              type: integer
              format: int64
  - name: p
    in: formData
    type: integer
    format: int64
    default: '0'
```

## 安装依赖

`npm install`

## 运行

`ZKADDR=127.0.0.1:2181 DEBUG=dubbo:* CLUSTERNUM=1 NO_DEPRECATION=koa node index.js`

打开浏览器访问 `http://127.0.0.1:3030` 即可看到 swagger ui 提供的基础参数界面；使用 `Try it out` 可以发起正常的表单输入；使用 `Execute` 即可发起dubbo RPC调用。

## Licensing

MIT

---
_Source: https://npm.io/package/dubbo-swagger · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._