swagger-ts-doc's Introduction

swagger-ts-doc

swagger-ts-doc 的灵感来自于swagger-jsdoc, swagger-jsdoc 会根据注释来生成对应的swagger描述, 搭配swagger-ui-express可以实现比较好的API文档,那么这里swagger-ts-doc 则是利用typescript 强类型的特新去生成swagger描述。

目标

swagger-ts-doc 参照了java的swagger文档生成方式，可以提供强类型的描述去产生对应的swagger API文档描述。

安装

$ npm install swagger-ts-doc --save

快速入门

Get started by documenting your code.

Demo 程序

$ git clone https://github.com/wz2cool/swagger-ts-doc-demo.git
$ cd swagger-ts-doc-demo
$ npm install
$ npm start

打开浏览器：http://localhost:3000/api-docs

swagger-ts-doc's People

Contributors

Stargazers

Watchers

swagger-ts-doc's Issues

如何统一添加request head

复杂数据怎么输出

我使用大神的demo稍微改造一下，但是出来的不是理想状态，
学生类 ./src/model/entity/student.ts

import { apiModelProperty, DataType } from "swagger-ts-doc";
import { Dog } from './dog';
export class Student {
    @apiModelProperty(DataType.STRING, false, "学生ID")
    public uuid: string;
    @apiModelProperty(DataType.STRING, false, "学生姓名")
    public name: string;
    @apiModelProperty(DataType.STRING, false, "学生年龄")
    public age: number;
    @apiModelProperty(DataType.ARRAY, false, "养的狗")
    public dogs: Array<Dog>;
}

狗类./src/model/entity/dog.ts

import { apiModelProperty, DataType } from "swagger-ts-doc";

export class Dog {
    @apiModelProperty(DataType.STRING, false, "狗名字")
    public name: string;
}

输出的json为

{"info":{"version":"1.0.0","title":"swagger-ts-demo"},"schemes":["http","https"],"definitions":{"AddStudentDto":{"type":"object","required":["name","age"],"properties":{"name":{"type":"string","description":"学生姓名"},"age":{"type":"integer","description":"学生年龄"}}},"UpdateStudentDto":{"type":"object","required":[],"properties":{"name":{"type":"string","description":"学生姓名"},"age":{"type":"integer","description":"学生年龄"}}},"Student":{"type":"object","required":[],"properties":{"uuid":{"type":"string","description":"学生ID"},"name":{"type":"string","description":"学生姓名"},"age":{"type":"string","description":"学生年龄"},"dogs":{"type":"array","description":"养的狗"}}}},"paths":{"/students":{"post":{"tags":["StudentApi"],"consumes":["application/json"],"produces":["application/json"],"parameters":[{"description":"新学生","in":"body","name":"student","required":true,"schema":{"$ref":"#/definitions/AddStudentDto"}}],"responses":{"200":{"description":"新学生ID","type":"string"},"409":{"description":"学生姓名冲突","type":"string"},"500":{"description":"内部错误","type":"string"}},"summary":"添加新学生"},"get":{"tags":["StudentApi"],"consumes":["application/json"],"produces":["application/json"],"parameters":[],"responses":{"200":{"description":"所有学生","type":"array","schema":{"items":{"$ref":"#/definitions/Student"}}}},"summary":"获取所有学生"}},"/students/{id}":{"delete":{"tags":["StudentApi"],"consumes":["application/json"],"produces":["application/json"],"parameters":[{"description":"学生ID","in":"path","name":"id","required":true,"type":"string"}],"responses":{"200":{"description":"ok","type":"string"},"404":{"description":"学生未找到","type":"string"},"500":{"description":"内部错误","type":"string"}},"summary":"删除学生"},"put":{"tags":["StudentApi"],"consumes":["application/json"],"produces":["application/json"],"parameters":[{"description":"学生ID","in":"path","name":"id","required":true,"type":"string"},{"description":"学生","in":"body","name":"student","required":true,"schema":{"$ref":"#/definitions/UpdateStudentDto"}}],"responses":{"200":{"description":"ok","type":"string"},"404":{"description":"学生未找到","type":"string"},"500":{"description":"内部错误","type":"string"}},"summary":"修改学生"}}},"swagger":"2.0"}

Recommend Projects