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

swagger-ts-shell

v1.0.5

Published

根据swagger-ts-api修改的一个本地运行的swagger

Downloads

2

Readme

swagger-ts-api

当前端web项目中应用了ts,我们不可能对成千上百的接口进行 interface的类型定义,那样效率是极低的,但是我们又需要ts智能友好的提示信息,该怎么办?这是我们必须要面对的问题。

介绍

根据swagger.json地址迅速生成ts接口,以及相关请求响应参的interface模块命令行工具。且支持swagger的V1、V2、V3版本。该插件的宗旨是利用swagger接口文档让前端的效率变得更高,接口的请求参、响应参以及接口命名将不在需要手动引入,让前端更聚焦在业务功能的开发,接口将全面与swagger进行同步。

我们该插件推荐大家结合gitnpm对生成的每个版本的ts请求文件进行版本管控,这样可以防止swagger变更带来的问题以便回退到旧的版本,因此你需要额外建立一个git用于存储本次生成的所有的api,一个npm发布管控npm包,项目组按照npm的版本进行拉去引入使用。

graph LR
A[api服务] -- 发布生成 --> B(swagger)
B -- 调用该插件 --> C{命令}
C -- -a命令添加-->D(生成ts请求文件与声明文件)
C -- -u命令更新 -->E(更新ts请求文件与声明文件)
D-->F(git)
E-->F
F-- 更新版本发布 -->G(npm)
G--拉取npm包-->前端业务代码

快速入门

1. 安装

npm install swagger-ts-shell -g 

2. 跟随引导操作

在自己目录中执行添加命令:
swagger-ts -a 
# 效果:
? 请输入swagger.json的相对地址 :v1/swagger.json
? 请输入生成api的名称 :test-api
✔ swagger api同步完成!

如何使用生成的接口

生成的api会变成以下目录:

        ├── test-api                           // 生成的api目录
        │   ├── swagger-api                    // 请求文件
        │   │   ├── index.ts                   
        │   ├── swagger-utils                  // 请求参数、响应参数的类型声明和接口定义
        │   │   ├── index.ts                   
        │   ├── main.ts                        // 入口文件,如果未发布npm可以直接导入该路径    
        │   ├── package.json                   // 备用,控制 api 版本
        │   ├── .npmignore                     // npm包发布过滤项 
        │   ├── README.md                      // api使用介绍 (这里是以发布npm为例的使用介绍)

我们每个接口都有对应的注释说明,这样也就方便大家直接检索,严格按照swagger文档进行解析而来,需要注意的是int64int32在前端js里面无法进行严格的区分,只有number类型,为避免numberjs长度限制所以我们这里会直接定义number|string类型.文件内容展示:

// test-api/swagger-api/index.ts

import * as types from './../swagger-utils/index'
import { HttpRequest } from './../main'
/**
 * 获取:地址编码[地址信息入参]
 */
export const mapGetGeo = (data: types.GetGeoDto) => {
  return HttpRequest().$post<types.GeoAddressVo>({
    url: '/infra/v1/Map/GetGeo',
    data: data
  })
}
// test-api/swagger-utils/index.ts

/**
* 获取:地址编码[地址信息入参]
*/
export interface GetGeoDto {
  address?: string;// 地址:结构化地址信息
  province?: string;// 省份
  city?: string;// 城市名称  
}

/**
* 获取:地址编码[地址信息入参]Res
*/
export interface GeoAddressVo {
  name: string;
  streetNumber: string;
  level: string;
  precise: boolean;
  confidence: integer;
  tenantId?: number|string;// 租户id
}

4. 如何使用生成的接口

生成后项目中,以xxx-api为例,项目内部有一个README.md 文件,可以按步骤操作或者点击使用说明

注意:

  1. 这里不建议大家添加swagger接口直接生成到开发项目中去,更建议大家结合npm私服的版本管理方式,否则每次更新将全部替换代码,让我们的前端代码变得不可控。
  2. 要求swagger文档字段定义清晰,不规范的文档将会有很多不可控的因素。
  3. 项目中接口方法命名,请求参原则上是以operationIdDTO进行命名,如果没有,插件将会以path路径后两位进行命名,如: /api/v1/abccodereport/getgoodnames => abccodereportGetgoodnames

⭐️⭐️⭐️⭐️⭐️⭐️⭐️⭐️开源不易,麻烦大家点个star,谢谢⭐️⭐️⭐️⭐️⭐️⭐️⭐️⭐️⭐️⭐️⭐️⭐️⭐️⭐️