使用swagger-codegen生成Java客户端

Swagger介绍

Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。

使用Swagger规范开发的接口，使用swagger的json/yaml格式的定义文件作为接口定义，类似以前的wsdl定义文件，包含接口方法以及一些模型对象定义。

拿到定义文件之后可以根据定义生成客户端，需要用到的工具就是swagger-codegen。

使用swagger-codegen可以使用maven插件方式，也可以使用命令行工具方式

使用命令生成

下载swagger-codegen

Github地址：swagger-codegen

下载地址（github上release只有源码，可以从maven仓库下载）:

搜索：https://search.maven.org/search?q=a:swagger-codegen-cli

https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.24/swagger-codegen-cli-3.0.24.jar

使用方法

查看帮助：

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

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)]
                .......................

生成代码

有很多可选的language（generators），这里使用jaxrs-cxf-client

java -jar swagger-codegen-cli-3.0.24.jar generate -i test.yml -l jaxrs-cxf-client -o output --remove-operation-id-prefix true --model-package com.citsgbt.gds.derby.bookingusb.model --api-package com.citsgbt.gds.derby.bookingusb.api

使用Maven插件生成

引入配置

最新版：

https://github.com/swagger-api/swagger-codegen/tree/v3.0.24/modules/swagger-codegen-maven-plugin

<plugin>
    <groupId>io.swagger.codegen.v3</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>3.0.24</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/:/api/bookingUsb.yml</inputSpec>
                <language>jaxrs-cxf-client</language>
                <configOptions>
                    <sourceFolder>src/gen/java/main</sourceFolder>
                </configOptions>
                <apiPackage>com.citsgbt.gds.derby.bookingusb.api</apiPackage>
                <modelPackage>com.citsgbt.gds.derby.bookingusb.model</modelPackage>
            </configuration>
        </execution>
    </executions>
</plugin>

参数：

• inputSpec - OpenAPI Spec file path
• language - target generation language
• output - target output path (default is ${project.build.directory}/generated-sources/swagger)
• templateDirectory - directory with mustache templates
• addCompileSourceRoot - add the output directory to the project as a source root (true by default)
• modelPackage - the package to use for generated model objects/classes
• apiPackage - the package to use for generated api objects/classes
• invokerPackage - the package to use for the generated invoker objects
• modelNamePrefix and modelNameSuffix - Sets the pre- or suffix for model classes and enums
• withXml - enable XML annotations inside the generated models and API (only works with Java language and libraries that provide support for JSON and XML)
• configOptions - a map of language-specific parameters (see below)
• configHelp - dumps the configuration help for the specified library (generates no sources)
• ignoreFileOverride - specifies the full path to a .swagger-codegen-ignore used for pattern based overrides of generated outputs
• generateApis - generate the apis (true by default)
• generateApiTests - generate the api tests (true by default. Only available if generateApis is true)
• generateApiDocumentation - generate the api documentation (true by default. Only available if generateApis is true)
• generateModels - generate the models (true by default)
• modelsToGenerate - A comma separated list of models to generate. All models is the default.
• generateModelTests - generate the model tests (true by default. Only available if generateModels is true)
• generateModelDocumentation - generate the model documentation (true by default. Only available if generateModels is true)
• generateSupportingFiles - generate the supporting files (true by default)
• supportingFilesToGenerate - A comma separated list of supporting files to generate. All files is the default.
• skip - skip code generation (false by default. Can also be set globally through the codegen.skip property)

生成代码

mvn clean compile