spring boot项目使用swagger-codegen生成服务间调用的jar包

swagger-codegen的github：https://github.com/swagger-api/swagger-codegen

需要的环境：jdk > 1.7 maven > 3.3.3

安装比较简单：

下载：

git clone git@github.com:swagger-api/swagger-codegen.git

下载完成后进入下载的文件夹里

mvn package

等着就可以了，我是用了两个小时完成编译的。

swagger-codegen目前还没太用明白，目前只用到了swagger-codegen-cli.jar包。这个jar包的位置在<download_package>/modules/swagger-codegen-cli/target/swagger-codegen-cli.jar。把它拷出来就行了。已经是一个功能完善的完整的jar包了。

查看用法：

$ 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.
　　version Show version information

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

主要介绍和spring-boot有关的用法，平常做spring-boot项目在服务间相互调用时一般都是RestTemplate，有了这个就不用了，可以生成client端的jar包，直接调用jar包中的方法就会进行服务调用。

首先需要会写yaml文件，还需要一个.json的配置文件，json文件可以有也可以没有，如果不用的话所有的参数就需要在命令行指定。

.yaml文件(这个文件的url是http://localhost:8888/{name} name是String的返回值是SwaggerResponse{data:String})生成 application/json

swagger: '2.0'

info:

  title: spring-cloud API

  description: Definition for test swagger-codegen

  version: 1.0.

host: localhost:

schemes:

- http

basePath: /

produces:

- application/json

paths:

  /{name}:

    get:

      summary: test

      operationId: swaggerCodegen

      description: test

      produces:

      - application/json

      parameters:

      - name: name

        in: path

        description: 名

        type: string

        required: true

      responses:

        :

          description: 返回结果

          schema:

            $ref: '#/definitions/SwaggerResponse'

definitions:

  SwaggerResponse:

    type: object

    properties:

      data:

        type: string

        description: 返回值

client端配置文件 spring-cloud.json：

{

    "groupId" : "cn.fzk",　　　　　　　　　　　　　　# 这三个就是 maven或gradle中下载jar包需要的三个参数

    "artifactId" : "spring-cloud-client",

    "artifactVersion" : "1.0.0",

    "library" : "feign",　　　　　　　　　　　　　　  # library template to use (官网说的还没太懂，和http请求有关，用了这个就需要在项目配置相关jar包)

    "invokerPackage" : "cn.com.client",　　　　　　# 相当于源文件的真正代码的位置

    "modelPackage" : "cn.com.client.model",　　　　# model存放的位置definitions下定义的东西

    "apiPackage" : "cn.com.client.api"　　　　　　 # API最终在DefaultApi中，这个文件的位置

}

client端依赖的jar包：(gradle dependencies)

dependencyManagement { imports { mavenBom 'org.springframework.cloud:spring-cloud-netflix:1.2.0.M1' } }

dependencies  {
  compile("com.netflix.feign:feign-core:8.17.0")

  compile("com.netflix.feign:feign-jackson:8.17.0")

  compile("com.netflix.feign:feign-slf4j:8.17.0")

  compile "com.fasterxml.jackson.core:jackson-core:2.7.5"

  compile "com.fasterxml.jackson.core:jackson-annotations:2.7.5"

  compile "com.fasterxml.jackson.core:jackson-databind:2.7.5"

  compile "com.fasterxml.jackson.datatype:jackson-datatype-joda:2.7.5"

  compile group: 'com.fasterxml.jackson.datatype', name: 'jackson-datatype-joda', version: '2.0.4'

  compile("io.github.openfeign.form:feign-form:2.1.0")

  compile("io.github.openfeign.form:feign-form-spring:2.1.0")
}

server端配置文件 spring-cloud-server.json：

{

    "groupId" : "cn.fzk",

    "artifactId" : "spring-cloud-server",

    "artifactVersion" : "1.0.0",

    "interfaceOnly" : "true",

    "library" : "spring-boot",

    "invokerPackage" : "cn.com.server",

    "modelPackage" : "cn.com.server.model",

    "apiPackage" : "cn.com.server.api"

}

生成jar包的方法。
client端： -i 指定生成API文件位置，-c 指定配置文件位置， -l 指定语言(下面会说)， -o 指定生成的文件存放的位置

java -jar swagger-codegen-cli.jar generate -i spring-cloud.yaml -c spring-cloud.json -l java -o client
cd client
mvn package

最终的jar包在target下有jar包，源码包，javadoc，test.jar。要的是spring-cloud-client-1.0.0.jar放到项目中。
项目中的使用方法：

　　　import cn.com.client.ApiClient;
　　 import cn.com.client.api.DefaultApi;
　　 import cn.com.client.model.SwaggerResponse;
　　 import cn.com.fzk.resource.Base;

    ApiClient apiClient = new ApiClient();

    apiClient.setBasePath("http://localhost:8888");　　　　　　　　　　　　//需要指定服务器的地址

    DefaultApi defaultApi = apiClient.buildClient(DefaultApi.class);

    SwaggerResponse res = defaultApi.swaggerCodegen(name);

server端： (如果server端已经写好其实可以不用server端)
spring-boot项目指定的语言： -l spring

java -jar swagger-codegen-cli.jar generate -i spring-cloud.yaml -c spring-cloud-server.json -l spring -o server
cd server
mvn package

生成的jar包同样在target下。
server端使用方法：

@RestController

public class SwaggerController implements NameApi {

  @RequestMapping(value = "/{name}", method = RequestMethod.GET)

  public ResponseEntity<SwaggerResponse> swaggerCodegen(@PathVariable("name") String name) {

    System.out.println(name);

    SwaggerResponse res = new SwaggerResponse();

    res.setData("i am " + name);

    return new ResponseEntity<SwaggerResponse>(res, HttpStatus.OK);

  }

}

需要说的一下是server端的返回值一直封装在ResponseEntity中。但是对前台及client端调用都不影响，最终接受到的仍然是真正的response，如果真的实在看不过去可以在最开始的编译前修改下源码：
spring server端源码的位置：swagger-codegen/modules/swagger-codegen/src/main/resources/JavaSpring下面的api.mustache 和 apiController.mustache文件。
打开文件就能看到ResponseEntity，但是修改的时候一定要注意别改错了。
最后自己写的小程序调用一下就可以了。说简单有点简单说难挺难的，yaml文件特别难写，建议在swagger-editor上编写，可以在网页上弄，最好还是下载到本地。

下面的东西就没用了，仅仅记录一下。

java -java swagger-codegen-cli.jar generate <options>

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

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

        --group-id <group id>

            groupId in generated pom.xml

        -i <spec file>, --input-spec <spec file>

            location of the swagger spec, as URL or file (required)

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

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

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

        --library <library>

            library template (sub-template)

        --model-package <model package>

            package for generated models

        -o <output directory>, --output <output directory>

            where to write the generated files (current dir by default)

        -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

        --reserved-words-mappings <import mappings>

            specifies how a reserved name should be escaped to. Otherwise, the

            default _<name> is used. For example id=identifier

        -v, --verbose

            verbose mode

config.json文件中可以生命的参数：

CONFIG OPTIONS

    modelPackage

        package for generated models

    apiPackage

        package for generated api classes

    sortParamsByRequiredFlag

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

    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

    library

        library template (sub-template) to use:

        jersey1 - HTTP client: Jersey client 1.18. JSON processing: Jackson 2.4.

        jersey2 - HTTP client: Jersey client 2.6

        feign - HTTP client: Netflix Feign 8.1..  JSON processing: Jackson 2.6.

        okhttp-gson (default) - HTTP client: OkHttp 2.4.. JSON processing: Gson 2.3.

        retrofit - HTTP client: OkHttp 2.4.. JSON processing: Gson 2.3. (Retrofit 1.9.)

        retrofit2 - HTTP client: OkHttp 2.5.. JSON processing: Gson 2.4 (Retrofit 2.0.-beta2

server端的说明：https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO

巴特西

spring boot项目使用swagger-codegen生成服务间调用的jar包

最新文章

热门文章