Swagger Codegen 自动生成Retrofit 代码

5,404 阅读8分钟

swagger是一个统一前后端的好工具,可以使用它来规划客户端的API访问规划,可以用来规划服务端接口的开发。这篇文章我介绍一下如何使用swagger codegen自动生成retrofit代码(rxjava2)。

如何使用swagger-codegen-cli生成retrofit 代码

开门见山,不BB,看看怎么自动生成代码

  • 下载swagger-codegen-cli.jar

    首先要我们先去下载swagger-codegen-cli.jar 包,写这篇文章的时候最新是3.0.0版本,下载地址在这里哟 ,下载下来的的文件名带有和版号,“swagger-codegen-cli-3.0.0-20170727.135949-1.jar”。觉得文件名太长,输入命令太累,而且容易出错误,所有我把它重命名了,“swagger-codegen-cli.jar”,当然你也可以根据自己喜欢重命名或不重命名它。

  • maven

    官方和许多网友说要安装maven,那就去下个maven,安装它,并把maven路径添加到环境变量path中。其实我好像没有安装maven的,但是我的retrofit代码还是生成成功了。

  • 写配制文件config.json

    新建个文件命名为config.json,在config.json文件中添加如下内容

    {
      "library": "retrofit2",
      "useRxJava2": "true",
      "developerName": "leix",
      "developerEmail": "",
      "developerOrganization": "albani.com",
      "invokerPackage": "com.albani.app",
      "modelPackage": "com.albani.app.data.entity",
      "apiPackage": "com.albani.app.data.api",
      "artifactId": "swagger-petstore-retrofit2"
    }
    
  • 准备swagger.json

    json文件和yml文件都是可以的,所以用editor生成swagger.json或swagger.yml

  • 见证奇迹了

    windows下运行cmd,输入如下命令:

    java -jar swagger-codegen-cli.jar generate -i swagger.json -o client -l java -c config.json
    

    回车,奇迹发生了,在你的client文件夹下生成了retrofit 网络请求代码,当然这个代码可能还是要根据需要做些小调整的。。

简单解析一下swagger-codegen的用法吧

上面代码已经生成了,但它是怎么动作的呢?在github上的文章说的比较清楚,下面来简单说说吧!

  • 在cmd中输入如下命名,获取帮助说明

    java -jar swagger-codegen-cli.jar help
    

    命令行打印出帮助说明

    usage: swagger-codegen-cli <command> [<args>]
    The most commonly used swagger-codegen-cli commands are:
        config-help   Config help for chosen lang
        generate      Generate code with chosen lang
        help          Display help information
        langs         Shows available 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.
        validate      Validate specification
        version       Show version information
    See 'swagger-codegen-cli help <command>' for more information on a specific
    command.
    
  • generate 使用说明

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

    命令行将打出generate相关的帮助说明

    NAME
            swagger-codegen-cli generate - Generate code with chosen lang
    SYNOPSIS
            swagger-codegen-cli generate
                    [(-a <authorization> | --auth <authorization>)]
                    [--additional-properties <additional properties>...]
                    [--api-package <api package>] [--artifact-id <artifact id>]
                    [--artifact-version <artifact version>]
                    [(-c <configuration file> | --config <configuration file>)]
                    [-D <system properties>...] [--git-repo-id <git repo id>]
                    [--git-user-id <git user id>] [--group-id <group id>]
                    [--http-user-agent <http user agent>]
                    (-i <spec file> | --input-spec <spec file>)
                    [--ignore-file-override <ignore file override location>]
                    [--import-mappings <import mappings>...]
                    [--instantiation-types <instantiation types>...]
                    [--invoker-package <invoker package>]
                    (-l <language> | --lang <language>)
                    [--language-specific-primitives <language specific primitives>...]
                    [--library <library>] [--model-name-prefix <model name prefix>]
                    [--model-name-suffix <model name suffix>]
                    [--model-package <model package>]
                    [(-o <output directory> | --output <output directory>)]
                    [--release-note <release note>] [--remove-operation-id-prefix]
                    [--reserved-words-mappings <reserved word mappings>...]
                    [(-s | --skip-overwrite)]
                    [(-t <template directory> | --template-dir <template directory>)]
                    [--type-mappings <type mappings>...] [(-v | --verbose)]
    OPTIONS
            -a <authorization>, --auth <authorization>
                adds authorization headers when fetching the swagger definitions
                remotely. Pass in a URL-encoded string of name:header with a comma
                separating multiple values
            --additional-properties <additional properties>
                sets additional properties that can be referenced by the mustache
                templates in the format of name=value,name=value. You can also have
                multiple occurrences of this option.
            --api-package <api package>
                package for generated api classes
            --artifact-id <artifact id>
                artifactId in generated pom.xml
            --artifact-version <artifact version>
                artifact version in generated pom.xml
            -c <configuration file>, --config <configuration file>
                Path to json configuration file. File content should be in a json
                format {"optionKey":"optionValue", "optionKey1":"optionValue1"...}
                Supported options can be different for each language. Run
                config-help -l {lang} command for language specific config options.
            -D <system properties>
                sets specified system properties in the format of
                name=value,name=value (or multiple options, each with name=value)
            --git-repo-id <git repo id>
                Git repo ID, e.g. swagger-codegen.
            --git-user-id <git user id>
                Git user ID, e.g. swagger-api.
            --group-id <group id>
                groupId in generated pom.xml
            --http-user-agent <http user agent>
                HTTP user agent, e.g. codegen_csharp_api_client, default to
                'Swagger-Codegen/{packageVersion}}/{language}'
            -i <spec file>, --input-spec <spec file>
                location of the swagger spec, as URL or file (required)
            --ignore-file-override <ignore file override location>
                Specifies an override location for the .swagger-codegen-ignore file.
                Most useful on initial generation.
            --import-mappings <import mappings>
                specifies mappings between a given class and the import that should
                be used for that class in the format of type=import,type=import. You
                can also have multiple occurrences of this option.
            --instantiation-types <instantiation types>
                sets instantiation type mappings in the format of
                type=instantiatedType,type=instantiatedType.For example (in Java):
                array=ArrayList,map=HashMap. In other words array types will get
                instantiated as ArrayList in generated code. You can also have
                multiple occurrences of this option.
            --invoker-package <invoker package>
                root package for generated code
            -l <language>, --lang <language>
                client language to generate (maybe class name in classpath,
                required)
            --language-specific-primitives <language specific primitives>
                specifies additional language specific primitive types in the format
                of type1,type2,type3,type3. For example:
                String,boolean,Boolean,Double. You can also have multiple
                occurrences of this option.
            --library <library>
                library template (sub-template)
            --model-name-prefix <model name prefix>
                Prefix that will be prepended to all model names. Default is the
                empty string.
            --model-name-suffix <model name suffix>
                Suffix that will be appended to all model names. Default is the
                empty string.
            --model-package <model package>
                package for generated models
            -o <output directory>, --output <output directory>
                where to write the generated files (current dir by default)
            --release-note <release note>
                Release note, default to 'Minor update'.
            --remove-operation-id-prefix
                Remove prefix of operationId, e.g. config_getId => getId
            --reserved-words-mappings <reserved word mappings>
                specifies how a reserved name should be escaped to. Otherwise, the
                default _<name> is used. For example id=identifier. You can also
                have multiple occurrences of this option.
            -s, --skip-overwrite
                specifies if the existing files should be overwritten during the
                generation.
            -t <template directory>, --template-dir <template directory>
                folder containing the template files
            --type-mappings <type mappings>
                sets mappings between swagger spec types and generated code types in
                the format of swaggerType=generatedType,swaggerType=generatedType.
                For example: array=List,map=Map,string=String. You can also have
                multiple occurrences of this option.
            -v, --verbose
                verbose mode
    

    讲一下我们用到的几个参数的意思

    • -i 表示输入的文件,editor生成的设计文件路径,如:-i d:/swagger/swagger.json

    • -o 代码生成目录,swagger codegen把代码生成到什么地方,如:-o d:/swagger/client

    • -l 生成代码语言,我们是生成java,如:-l java

    • -c 配置文件,配制文件路径,如:-c d:/swagger/config.json

  • config说明

    写了个config.json文件,但是这个文件里的设置到底是些什么鬼呢?下面我们来看看config的帮助,输入以下命令获取帮助说明

    java -jar swagger-codegen-cli.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)
            allowUnicodeIdentifiers
                boolean, toggles whether unicode identifiers are allowed in names or not, default is false (Default: false)
            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
            artifactUrl
                artifact URL in generated pom.xml
            artifactDescription
                artifact description in generated pom.xml
            scmConnection
                SCM connection in generated pom.xml
            scmDeveloperConnection
                SCM developer connection in generated pom.xml
            scmUrl
                SCM URL in generated pom.xml
            developerName
                developer name in generated pom.xml
            developerEmail
                developer email in generated pom.xml
            developerOrganization
                developer organization in generated pom.xml
            developerOrganizationUrl
                developer organization URL in generated pom.xml
            licenseName
                The name of the license
            licenseUrl
                The URL of the license
            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
            withXml
                whether to include support for application/xml content type. This option only works for Java API client (resttemplate) (Default: false)
            dateLibrary
                Option. Date library to use
                    joda - Joda (for legacy app only)
                    legacy - Legacy java.util.Date (if you really have a good reason not to use threetenbp
                    java8-localdatetime - Java 8 using LocalDateTime (for legacy app only)
                    java8 - Java 8 native JSR310 (preferred for jdk 1.8+) - note: this also sets "java8" to true
                    threetenbp - Backport of JSR310 (preferred for jdk < 1.8)
            java8
                Option. Use Java8 classes instead of third party equivalents
                    true - Use Java 8 classes such as Base64
                    false - Various third party libraries as needed
            useRxJava
                Whether to use the RxJava adapter with the retrofit2 library. (Default: false)
            useRxJava2
                Whether to use the RxJava2 adapter with the retrofit2 library. (Default: false)
            parcelableModel
                Whether to generate models for Android that implement Parcelable with the okhttp-gson library. (Default: false)
            usePlay24WS
                Use Play! 2.4 Async HTTP client (Play WS API) (Default: false)
            supportJava6
                Whether to support Java6 with the Jersey1 library. (Default: false)
            useBeanValidation
                Use BeanValidation API annotations (Default: false)
            performBeanValidation
                Perform BeanValidation (Default: false)
            useGzipFeature
                Send gzip-encoded requests (Default: false)
            useRuntimeException
                Use RuntimeException instead of Exception (Default: false)
            library
                library template (sub-template) to use (Default: okhttp-gson)
                    jersey1 - HTTP client: Jersey client 1.19.4. JSON processing: Jackson 2.8.9. Enable Java6 support using '-DsupportJava6=true'. Enable gzip request encoding using '-DuseGzipFeature=true'.
                    feign - HTTP client: OpenFeign 9.4.0. JSON processing: Jackson 2.8.9
                    jersey2 - HTTP client: Jersey client 2.25.1. JSON processing: Jackson 2.8.9
                    okhttp-gson - HTTP client: OkHttp 2.7.5. JSON processing: Gson 2.8.1. Enable Parcelable models on Android using '-DparcelableModel=true'. Enable gzip request encoding using '-DuseGzipFeature=true'.
                    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.8.0. JSON processing: Gson 2.6.1 (Retrofit 2.3.0). Enable the RxJava adapter using '-DuseRxJava[2]=true'. (RxJava 1.x or 2.x)
                    resttemplate - HTTP client: Spring RestTemplate 4.3.9-RELEASE. JSON processing: Jackson 2.8.9
                    resteasy - HTTP client: Resteasy client 3.1.3.Final. JSON processing: Jackson 2.8.9
    

    介绍下我们用到的几个主要参数

    • library,生成的代码支付的类,有jersey1、jersey2、okhttp-gson、resttemplate、resteasy、feign、retrofit、retrofit2等几种类型,我们选择的retrofit2
    • developerName,开发者名字,会出现在代码文件里
    • developerEmail,开发者邮箱,会出现在代码文件里
    • developrOrganization,开发者组织,会出现在代码里
    • invokerPackage,项目的包名
    • apiPackage,生成的***Api.java文件的包名
    • modelPackage,生成的数据模型java文件包名
    • dateLibrary,时间使用的类开
    • useRxJava,是否使用rxjava生成api接口
    • useRxJava2,是否使用rxjava2的方式调用接口,在这里我们设为true