Swagger Codegen离线的内网中自动生成代码

前言

Swagger Codegen是一个开源代码生成器，可直接从Swagger定义的RESTful API(json或yaml格式)构建服务端和客户端代码。

虽然我们可以直接在网站上使用swagger-editor(http://editor.swagger.io)生成代码，但是，有时我们也有在内网中生成代码的需求。

本文将以NodeJS-Server为例，介绍如何在离线的内网环境中使用Swagger Codegen生成服务端代码。

1.环境

操作系统 ： windows 7 64bit

Java ： 1.8.0 64bit

Swagger Codegen： 2.4.9

(https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.9/swagger-codegen-cli-2.4.9.jar)

Swagger Editor ： 3.7.1

NodeJS : 12.13.0 64bit

2.Swagger Codegen用法简介

2.1 查看支持语言

java -jar swagger-codegen-cli-2.4.9.jar

Available languages: [ada, ada-server, akka-scala, android, apache2, apex, aspnetcore, bash, csharp, clojure, cwiki, cpprest, csharp-dotnet2, dart, dart-jaguar, elixir, elm, eiffel, erlang-client, erlang-server, finch, flash, python-flask,go, go-server, groovy, haskell-http-client, haskell, jmeter, jaxrs-cxf-client, jaxrs-cxf, java, inflector, jaxrs-cxf-cdi, jaxrs-spec, jaxrs, msf4j, java-pkmst,java-play-framework, jaxrs-resteasy-eap, jaxrs-resteasy, javascript, javascript-closure-angular, java-vertx, kotlin, lua, lumen, nancyfx, nodejs-server, objc, perl, php, powershell, pistache-server, python, qt5cpp, r, rails5, restbed, ruby, rust, rust-server, scala, scala-gatling, scala-lagom-server, scalatra, scalaz,php-silex, sinatra, slim, spring, dynamic-html, html2, html, swagger, swagger-yaml, swift4, swift3, swift, php-symfony, tizen, typescript-aurelia, typescript-angular, typescript-inversify, typescript-angularjs, typescript-fetch, typescript-jquery, typescript-node, undertow, ze-ph, kotlin-server]

2.2 查看帮助信息

java -jar swagger-codegen-cli-2.4.9.jar help generate

2.3 生成代码

语法：

java -jar swagger-codegen-cli-2.2.1.jar generate -i <path of your Swagger specification> -l <language>

示例：

java -jar swagger-codegen-cli-2.4.9.jar generate -i http://petstore.swagger.io/v2/swagger.json -l nodejs-server -o samples

生成代码的目录结构：

3.自定义swagger Restful API

下图为swagger-editor的自定义json/yaml的可视化界面，其语法为Swagger specification Version 2.0(https://swagger.io/specification/v2/)，格式可以为json、yaml。

swagger: "2.0"

info:
 version: 1.0.0
 title: Restful API接口
 description: Restful API v1.0.0.191127
 contact: 
 name: itas109
 email: itas109@qq.com
schemes:
 - http
 - https
produces:
 - application/json
 - text/plain
host: "127.0.0.1:8080"
#basePath: /api/v1.0
tags:
- name: "user"
 description: "用户管理相关"
paths:
 /user/login :
 get :
 tags : ["user"]
 summary: 用户登录
 description: login 用户登录
 parameters:
 - name : user_name
 in : query
 required: true
 description : 用户名
 type : string
 - name : password
 in : query
 required: true
 description : 密码
 type : string
 responses : 
 200:
 description: 登录成功返回句柄 {"user_handle":"***"}，失败则返回空 {"user_handle":""}
 schema:
 $ref: "#/definitions/ApiResponse"
 default:
 description: Unexpected error
definitions:
 ApiResponse: # 通用api返回
 example: {"error_code":0,"message":"成功","total":1,"datas":[{"xxx":"xxx"}]}
 type: object
 properties: 
 error_code: 
 type: integer
 format: int32
 description: "系统级级错误码:\n 0 成功 \n 100101 内部系统异常 \n 100201接口维护 \n 100202 接口停用 \n\n 服务级错误码:\n 200101 查询参数为空 \n 200102 入口参数错误 \n 200103 权限不足"
 message: 
 type: string
 description: "返回说明"
 total:
 type: integer
 format: int32
 description: "返回结果集数组个数"
 datas:
 type: string
 description: "返回结果集，一般为json格式"

导出yaml(推荐)或json

4.Swagger Codegen利用自定义swagger.yaml生成nodejs-server代码

java -jar swagger-codegen-cli-2.4.9.jar generate -i swagger.yaml -l nodejs-server -o samples

进入samples目录，执行

npm start

或者

npm install

node index.js

浏览器访问：http://localhost:8080/docs