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  -l 

示例：

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-editor

swagger: "2.0"

info:
 version: 1.0.0
 title: Restful API接口
 description: Restful API v1.0.0.191127
 contact: 
 name: itas109
 email: [email protected]
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

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

node index.js

瀏覽器訪問：http://localhost:8080/docs

瀏覽器訪問