• 52389

    文章

  • 521

    评论

  • 43

    友链

  • 最近新加了换肤功能,大家多来逛逛吧~~~~
  • 喜欢这个网站的朋友可以加一下QQ群,我们一起交流技术。

swagger-codegen生成java客户端代码

695856371Web网页设计师②群 | 喜欢本站的朋友可以收藏本站,或者加入我们大家一起来交流技术!

欢迎来到梁钟霖个人博客网站。本个人博客网站提供最新的站长新闻,各种互联网资讯。 还提供个人博客模板,最新最全的java教程,java面试题。在此我将尽我最大所能将此个人博客网站做的最好! 谢谢大家,愿大家一起进步!

前后端分离的时候,需要建立契约,Swagger可达到该目的(略)。

建立Rest接口后,通过swagger-codegen项目可以自动生成对应的客户端代码(c++、php、java、js、node等等),

关于swagger-codegen项目的使用,发现中文文档较少,追根述源后,发现其中相当一部分同出一辙。

亲自摸索使用后,记录一下步骤,利己利人。

swagger-codegen项目地址: https://github.com/swagger-api/swagger-codegen

项目文档(README.md)说的比较详细,但是重复的地方太多,容易让新手搞晕。

其实,文档内容可以简化为如下步骤(凡‘略’,皆不予理睬):

【注意】以下步骤,均在Windows系统中操作,生成java客户端代码,其他语言类似;英文不好,有些不会翻译,故保留英文原文;

1、Table of contents(略)

2、Compatibility(略)

3、Prerequisites

  3.1、从maven仓库下载swagger-codegen的jar文件,如下

  <!-- https://mvnrepository.com/artifact/io.swagger/swagger-codegen -->

  <dependency>

    <groupId>io.swagger</groupId>

    <artifactId>swagger-codegen</artifactId>

    <version>2.2.1</version>

  </dependency>

  放到本地目录(比如D:\env\swagger-codegen-cli-2.2.1.jar);

  3.2、本机安装JDK7+,并设置$PATH(比如:D:\Java\jdk1.8.0_60\bin;);

  3.3、本机安装Maven3.3.3+,并设置$PATH(比如:D:\apache-maven-3.3.3\bin;);

4、Building(略)

5、Docker(略)

6、Homebrew(略)

7、Getting Started

  dos窗口中,执行如下命令(Windows系统下,换行符无效,必须写在同一行):

  java -jar D:\env\swagger-codegen-cli-2.2.1.jar generate 

  -i http://petstore.swagger.io/v2/swagger.json 

  -l java 

  -o D:\swagger-client 

  --model-package com.xxx.client.model 

  --api-package com.xxx.client.api

  【参数说明】

  -jar 指定 swagger-codegen-cli-2.2.1.jar 的位置,绝对路径、相对路径均可;

  -i 指定 swagger.json 的位置,本地路径、网络路径均可;

  -l 指定客户端代码的语言;

  -o 指定代码生成的位置;

  --model-package 指定model代码的包名;

  --api-package 指定api代码的包名;

8、Workflow Integration(略)

9、Github Integration(略)

 

【补充后续操作步骤】

10、将生成的代码拷贝到项目中(api、model、test)

11、pom.xml添加依赖(仅操作一次)

<!-- swagger-begin -->

<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-jaxrs</artifactId>
  <version>1.5.9</version>
</dependency>
<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-annotations</artifactId>
  <version>1.5.9</version>
</dependency>
<dependency>
  <groupId>com.squareup.okhttp</groupId>
  <artifactId>okhttp</artifactId>
  <version>2.7.5</version>
</dependency>
<dependency>
  <groupId>com.squareup.okhttp</groupId>
  <artifactId>logging-interceptor</artifactId>
  <version>2.7.5</version>
</dependency>
<dependency>
  <groupId>com.google.code.gson</groupId>
  <artifactId>gson</artifactId>
  <version>2.6.2</version>
</dependency>
<dependency>
  <groupId>joda-time</groupId>
  <artifactId>joda-time</artifactId>
  <version>2.9.3</version>
</dependency>
<!-- swagger-end -->

12、修改ApiClient.java(一般来说,该文件无须覆盖,仅操作一次)

  12.1、修改属性 basePath的值,自己的api根路径;

  12.2、如果需要ssl,或者url追加token,需要修改 buildUrl()方法;

13、执行测试代码即可(生成的测试代码,方法体是空的,需要自己补充代码);

 

【补充】

A、下载源代码:

下载最新代码

> git clone https://github.com/swagger-api/swagger-codegen.git

 

下载指定版本

> git clone --branch v2.2.1 https://github.com/swagger-api/swagger-codegen.git

 

B、查看swagger-codegen支持的命令

> java -jar swagger-codegen-cli-2.2.1.jar help

  用法: swagger-codegen-cli <command> [<args>]

  常用命令如下:
  config-help   指定客户端语言的可选项说明
  generate      生成客户端代码命令
  help          帮助
  langs         显式所有支持的语言
  meta          MetaGenerator. Generator for creating a new template set and configuration for Codegen.  The output will be based on the language you specify, and includes default templates to include.


See 'swagger-codegen-cli help <command>' for more information on a specific command.

 

C、查看swagger-codegen的generate命令的可选项

> java -jar swagger-codegen-cli-2.2.1.jar help generate

NAME

  swagger-codegen-cli generate - Generate code with chosen lang

SYNOPSIS

  swagger-codegen-cli generate [options]

OPTIONS

  -a <authorization>

    当获取远程swagger定义时,添加授权头信息;URL-encoded格式化的name,逗号隔开的多个值;

  --auth <authorization>

    同 -a;

  --additional-properties <additional properties>

    设置额外的属性供模版使用;格式为name=value,name=value;

  --api-package <api package>

    指定生成的api类的包名;

  --artifact-id <artifact id>

    指定pom.xml的artifactId的值;

  --artifact-version <artifact version>

    指定pom.xml的artifact的版本;

  -c <configuration file>

    json格式的配置文件的路径;文件为json格式,支持的配置项因语言的不同而不同;

    执行 config-help -l {lang} 命令查看详细的配置项;

  --config <configuration file>

    同 -c;

  -D <system properties>

    指定系统属性,格式为name=value,name=value;

  --group-id <group id>

    指定pom.xml的groupId的值;

  -i <spec file>

    指定swagger描述文件的路径,url地址或路径文件;该参数为必须;

  --input-spec <spec file>

    同 -i;

  --import-mappings <import mappings>

    specifies mappings between a given class and the import that should be used for that class,

    格式type=import,type=import;

  --instantiation-types <instantiation types>

    设置实例类型映射,格式type=instantiatedType,type=instantiatedType.

    例如(in Java):array=ArrayList,map=HashMap.换句话说,生成代码时,array类型会实例化为ArrayList;

  --invoker-package <invoker package>

    指定根包名称;

  -l <language>

    指定生成客户端代码的语言,该参数为必须;

  --lang <language>

    同 -l;

  --language-specific-primitives <language specific primitives>

    指定附加语言特定的原始类型,格式type1,type2,type3,type3.例如:String,boolean,Boolean,Double;

  --library <library>

    library template (sub-template);

  --model-package <model package>

    指定生成的model类的包名;

  -o <output directory>

    指定生成文件的位置(默认当前目录);

  --output <output directory>

    同 -o;

  -s

    指定该参数表示不覆盖已经存在的文件;

  --skip-overwrite

    同 -s;

  -t <template directory>

    指定模版文件所在目录;

  --template-dir <template directory>

    同 -t;

  --type-mappings <type mappings>

    设置swagger类型与生成的代码类型之间的映射,格式swaggerType=generatedType,swaggerType=generatedType.

    例如: array=List,map=Map,string=String;

  -v

    指定verbose mode;

  --verbose

    同 -v;

 

 

D、查看java客户端的可配置项

> java -jar swagger-codegen-cli-2.2.1.jar config-help -l java

CONFIG OPTIONS

  sortParamsByRequiredFlag

    Sort method arguments to place required parameters before optional parameters. (Default: true)

  ensureUniqueParams

    Whether to ensure parameter names are unique in an operation (rename parameters that are not). (Default: true)

  modelPackage

 package for generated models

  apiPackage

    package for generated api classes

  invokerPackage

    root package for generated code

  groupId

 groupId in generated pom.xml

  artifactId

 artifactId in generated pom.xml

  artifactVersion

    artifact version in generated pom.xml

  sourceFolder

source folder for generated code

  localVariablePrefix

    prefix for generated code members and local variables

  serializableModel

    boolean - toggle "implements Serializable" for generated models (Default: false)

  bigDecimalAsString

    Treat BigDecimal values as Strings to avoid precision loss. (Default: false)

  fullJavaUtil

 whether to use fully qualified name for classes under java.util.

    This option only works for Java API client (Default: false)

  hideGenerationTimestamp

    hides the timestamp when files were generated

  dateLibrary

 Option. Date library to use

      joda - Joda

      legacy - Legacy java.util.Date

      java8-localdatetime - Java 8 using LocalDateTime (for legacy app only)

      java8 - Java 8 native

  useRxJava

 Whether to use the RxJava adapter with the retrofit2 library. (Default: false)

  library

 library template (sub-template) to use (Default: okhttp-gson)

      jersey1 - HTTP client: Jersey client 1.19.1. JSON processing: Jackson 2.7.0

      feign - HTTP client: Netflix Feign 8.16.0. JSON processing: Jackson 2.7.0

      jersey2 - HTTP client: Jersey client 2.22.2. JSON processing: Jackson 2.7.0

      okhttp-gson - HTTP client: OkHttp 2.7.5. JSON processing: Gson 2.6.2

      retrofit - HTTP client: OkHttp 2.7.5. JSON processing: Gson 2.3.1 (Retrofit 1.9.0).

        IMPORTANT NOTE: retrofit1.x is no longer actively maintained so please upgrade to 'retrofit2' instead.

      retrofit2 - HTTP client: OkHttp 3.2.0. JSON processing: Gson 2.6.1 (Retrofit 2.0.2). 

        Enable the RxJava adapter using '-DuseRxJava=true'. (RxJava 1.1.3)

 

E、查看swagger-codegen支持的客户端语言

> java -jar swagger-codegen-cli-2.2.1.jar langs

(结果略)

或参考 https://github.com/swagger-api/swagger-codegen/wiki/API-client-generator-HOWTO

 

F、服务器端代码生成,参考https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO

 

G、swagger支持的数据类型映射

http://swagger.io/specification/

参考代码:DefaultCodegen.java

  this.typeMapping = new HashMap();
  this.typeMapping.put("array", "List");
  this.typeMapping.put("map", "Map");
  this.typeMapping.put("List", "List");
  this.typeMapping.put("boolean", "Boolean");
  this.typeMapping.put("string", "String");
  this.typeMapping.put("int", "Integer");
  this.typeMapping.put("float", "Float");
  this.typeMapping.put("number", "BigDecimal");
  this.typeMapping.put("DateTime", "Date");
  this.typeMapping.put("long", "Long");
  this.typeMapping.put("short", "Short");
  this.typeMapping.put("char", "String");
  this.typeMapping.put("double", "Double");
  this.typeMapping.put("object", "Object");
  this.typeMapping.put("integer", "Integer");
  this.typeMapping.put("ByteArray", "byte[]");
  this.typeMapping.put("binary", "byte[]");

 

遗留问题:

1、还不清楚如何将api数据类型和java的数据类型进行映射;

--------------------- 本文来自 wangjunjun2008 的CSDN 博客 ,全文地址请点击:https://blog.csdn.net/wangjunjun2008/article/details/53200437?utm_source=copy


 转载至链接:https://my.oschina.net/u/133911/blog/2221741。


转载原创文章请注明出处,转载至: 梁钟霖个人博客www.liangzl.com

您觉喜欢本网站,或者觉得本文章对您有帮助,那么可以选择打赏。
打赏多少,您高兴就行,谢谢您对梁钟霖这小子的支持! ~(@^_^@)~

  • 微信扫一扫

  • 支付宝扫一扫

    支付宝打赏

2条评论

Loading...
  • 和规范经营299L

    和他人家庭人口教育投入款

  • shizhipeng293L

    sb 你敢不敢写的清楚一点,不要祸害别人,写的是你嘛的bi啊



发表评论

电子邮件地址不会被公开。 必填项已用*标注

自定义皮肤
注册梁钟霖个人博客