Swagger Codegen使用

一、Swagger Codegen简介

Swagger Codegen是一个开源的代码生成器，根据Swagger定义的RESTful API可以自动建立服务端和客户端的连接。官方简介看这里：Swagger Codegen

二、Swagger简单使用

新建一个SpringBoot项目

引入依赖

        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox.version}</version>
       </dependency>

使用Swagger注解：

@Api(tags = {"user. 用户管理"})
public class OneController {

    @GetMapping(value = "/{id}")
    @ApiOperation("根据id查用户")
    @ResponseStatus(code = HttpStatus.OK)
    @ApiImplicitParam(paramType = "path", dataType = "string", name = "id", value = "用户id", required = true)
    public UserDto getUser(@PathVariable String id) {
        UserDto userDto = UserDto.builder()
                .age(10)
                .gender("F")
                .build();
        userDto.setId(id).setName("无名");
        return userDto;
    }
}

@ApiModel(value = "用户Dto")
public class UserDto extends IdName {
    @ApiModelProperty("性别")
    private String gender;

    @ApiModelProperty("年龄")
    private int age;
}

启用项目之后，访问Swagger地址，看看效果：

三、使用Swagger Codegen根据服务生成客户端代码

这里有两种方式，一种是使用swagger-codegen-cli的jar包，在命令行里面生成，如下：

java -jar swagger-codegen-cli-2.3.0.jar generate 
	-i http://localhost:8080/v2/api-docs   （swagger文档地址）
	-l java  
	--library resttemplate 
	-o magellan-configuration-center-client 
	--api-package XXX.client.api
	--invoker-package XXX.client.invoker 
	--model-package XXX.client.model
	--group-id cn.XXX 
	--artifact-id  XXX-api
	--artifact-version 1.0.0-SNAPSHOT

还有一种就是使用maven插件，引入如下插件：

<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.4.9</version>
    <configuration>
        <!--FIXME:如何避免打包后转化为https-->
        <inputSpec>http://localhost:8080/v2/api-docs</inputSpec>
        <language>java</language>
        <library>resttemplate</library>
        <groupId>com.example</groupId>
        <artifactId>service-one-swagger-api-client</artifactId>
        <modelPackage>${groupId}.service-one.client.model</modelPackage>
        <apiPackage>${groupId}.service-one.client.api</apiPackage>
        <invokerPackage>${groupId}.service-one.client.invoker</invokerPackage>
        <output>${project.basedir/api-client}</output>
    </configuration>
    <executions>
        <execution>
            <id>generate-swagger-javaclient</id>
            <phase>generate-sources</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>			

然后，点击插件：

可以生成客户端代码，我们这里指定了在api-client目录下，可以看到已经生成了如下代码结构：

编译之后将其install到本地。

四、client的使用

重建一个项目，引入上面Swagger Codegen生成的jar包：

   		<dependency>
            <groupId>com.example</groupId>
            <artifactId>service-one-swagger-api-client</artifactId>
            <version>1.0.0</version>
        </dependency>

然后调用ServiceOne中Controller提供的getUser方法：

    @Autowired
    User_Api userApi;

    @Override
    public String getName() {
        Dto dto = userApi.getUserUsingGET("userIdFromProduct");
        log.info(dto.toString());
        return dto.getName();
    }

此处的User_Api是Swagger自动生成的类名，根据@Api(tags = {“user. 用户管理”})
中的tag生成的，应该是可以修改的，还需继续研究。

在Test中调用此方法，可以看到可以正常输出方法。这也可以作为一种服务间调用的方式。