npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

qianmi-egg-swagger

v0.1.3

Published

针对ts类型的eggjs项目自动生成swagger的接口文档插件

Downloads

1

Readme

ts-egg-swagger插件

目标

让 基于typescript的eggjs项目可以像 javaBFF 一样,通过约定配置,就可以生成swagger接口文档。

目录结构

.
├── lerna.json
├── package.json
├── packages
│   ├── egg-example-------插件使用demo
│   └── egg-swagger-------egg-swagger插件
└── readme.md

配套使用的vscode代码提示插件 egg-code-prompt https://github.com/JustinYi922/egg-code-prompt

插件原理

  1. 解析路由,可以知道有多少请求
  2. 解析 controller目录下面的所有类来获取模块
  3. 解析controller对应的目录typings下的custom下的相同名称的.d.ts 的声明文件(另外typings下面的common.d.ts存放公共的类型信息)
  4. 生成 swagger 的 openApi 规范 json 文件
  5. 保存到本地或上传 Yapi

怎么使用

  • 下单插件
npm install qianmi-egg-swagger --save-dev
  • 配置插件

建议是写在 package.json 的 scripts.postpublish 里面

用swagger-ui生成在线文档

"ui": "./node_modules/.bin/qm-egg-doc swagger-ui"

发布到指定的yapi

"doc": "./node_modules/.bin/qm-egg-doc --yapi <这里yapi的post请求地址>"

swagger 规范

https://swagger.io/specification/v2/

怎么使用?

路由

规则:http 请求+url+controller 路径+方法

//模拟get请求 path
router.get(
  "/delivery/address/list/:phonenum",
  controller.deliveryAddress.addressList
);
//模拟get请求 query
router.get("/delivery/address/update", controller.deliveryAddress.update);
//模拟post请求
router.post("/delivery/address/add", controller.deliveryAddress.add);
//模拟all请求
router.all("/delivery/address/delete", controller.deliveryAddress.delete);

controller

import { Controller } from 'egg';

/**
 * 配送管理
 */
export default class DeliveryAddress extends Controller {
  /**
   * 方法名称
   * @path phonenum string 手机号
   */
  public async addressList() {

    this.ctx.response.success(null);
  }

  /**
   * 方法名称
   * @query province string 省 required
   * @query city string 市 required
   * @query area string 区
   */
  public async update() {
    this.ctx.response.success(null);
  }


  /**
   * 方法名称
   * @request IAddressAddParam
   */
  public async add() {
    this.ctx.response.success(null);
  }
  /**
   * 方法名称
   * @response AddressDTO
   */
  public async delete() {
    this.ctx.response.success(null);
  }

  /***
   * 方法名称
   * @response IBaseDTO<ICityDelivery>
   */
  public async cityDeliveryAddress() {
    this.ctx.response.success(addressList);
  }

}

声明文件

declare module 'shop' {

  interface IAddressAddParam {
    /**
     * 手机号码
     */
    mobile: string;
    receiptUserMobile: string;
    receiptUserName: string;
    address: string;
    /**
     * 经度纬度
     */
    latitude: number;
    longitude: number;
    /**
     * 地址备注
     */
    addressRemark?: string;
    /**
     * 是否默认
     */
    isDefault?: boolean;
  }

  interface AddressDTO{
    /**
     * 手机号码
     *
     */
     mobile: string;
     receiptUserMobile: string;
     receiptUserName: string;
     address: string;
     /**
      * 经度纬度
      */
     latitude: number;
     longitude: number;
     /**
      * 地址备注
      */
     addressRemark?: string;
     /**
      * 是否默认
      */
     isDefault?: boolean;
  }
}

注意

  1. 生成接口文档,技术只是实现而已,最重要的是约定和完善接口信息
  2. 文件名如果有多个单词,请以英文-分割
  3. 代码中路径和关键词等命名请用驼峰的形式
  4. 请把 typings/custom 文件下的路径和名称与 controller 下面的文件的路径保持一致

不足

  • 还有很多功能未实现;
  • 暂未支持直接访问 swagger 页面
  • 如有 bug 请及时告知,或者一起修改一下哈
  • 返回值是基本类型处理