Swagger使用笔记_supportingfilestogenerate

Swagger使用笔记

使用Swagger Codegen生成代码

参考github:https://github.com/swagger-api/swagger-codegen
先在项目pom中增加依赖：

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.4.17</version>
</dependency>
1
2
3
4
5

增加依赖后就可以看到插件的源码了，后面碰到问题翻一下代码也方便

插件介绍

Gittee仓库：https://gitee.com/mirrors/swagger-codegen?_from=gitee_search
官方介绍：

总结：关键词OpenAPI、服务端、客户端、文档。swagger-codegen可以根据符合OpenAPI定义规范的文件，生成对应的服务端、客户端代码，接口的说明文档。

调用方式

目前我了解的调用方式主要有以下两种：

1. 通过官方提供的jar包直接调用 java swagger-codegen-cli.jar xx xx
2. 通过集成maven插件，在pom中执行编译步骤调用，本篇文章也主要用这种方式。

生成服务端代码

1. 定义接口描述文件yaml
   以一个最简单的get接口为例，yaml内容如下：

swagger: "2.0"
info:
  description: "测试swagger"
  version: "1.0.0"
  title: "测试api"

paths:
  /test:
    get:
      consumes:
        - application/json
      produces:
        - application/json
      response:
        200:
          description: 成功
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

目录结构：
3. 配置maven编译步骤，调用swagger-codegen-maven-plugin

<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.3.1</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/test.yaml</inputSpec>
                <language>spring</language>
                <library>spring-mvc</library>
                <apiPackage>blog.test</apiPackage>
                <output>${project.basedir}/generate</output>
                <generateSupportingFiles>false</generateSupportingFiles>
            </configuration>
        </execution>
    </executions>
</plugin>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

默认执行phase：

CodeGenMojo.class
@Mojo(
    name = "generate",
    defaultPhase = LifecyclePhase.GENERATE_SOURCES,
    threadSafe = true
)
1
2
3
4
5
6

具体的参数配置可以参考github上官方代码库，或者看插件源码也行：
gittee地址：https://gitee.com/mirrors/swagger-codegen/tree/master/modules/swagger-codegen-maven-plugin
最终生成的效果：
目录结构：

TestApi.class
/**
 * NOTE: This class is auto generated by the swagger code generator program (2.3.1).
 * https://github.com/swagger-api/swagger-codegen
 * Do not edit the class manually.
 */
package blog.test;

import io.swagger.annotations.*;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RequestPart;
import org.springframework.web.multipart.MultipartFile;

import javax.validation.Valid;
import javax.validation.constraints.*;
import java.util.List;
@javax.annotation.Generated(value = "io.swagger.codegen.languages.SpringCodegen", date = "2020-12-27T10:58:24.379+08:00")

@Api(value = "test", description = "the test API")
public interface TestApi {

    @ApiOperation(value = "", nickname = "testGet", notes = "", tags={  })
    @ApiResponses(value = {  })
    @RequestMapping(value = "/test",
        produces = { "application/json" }, 
        consumes = { "application/json" },
        method = RequestMethod.GET)
    ResponseEntity<Void> testGet();

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

TestApiController.class
package blog.test;

import com.fasterxml.jackson.databind.ObjectMapper;
import io.swagger.annotations.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RequestPart;
import org.springframework.web.multipart.MultipartFile;

import javax.validation.constraints.*;
import javax.validation.Valid;
import javax.servlet.http.HttpServletRequest;
import java.io.IOException;
import java.util.List;
@javax.annotation.Generated(value = "io.swagger.codegen.languages.SpringCodegen", date = "2020-12-27T10:58:24.379+08:00")

@Controller
public class TestApiController implements TestApi {

    private static final Logger log = LoggerFactory.getLogger(TestApiController.class);

    private final ObjectMapper objectMapper;

    private final HttpServletRequest request;

    @org.springframework.beans.factory.annotation.Autowired
    public TestApiController(ObjectMapper objectMapper, HttpServletRequest request) {
        this.objectMapper = objectMapper;
        this.request = request;
    }

    public ResponseEntity<Void> testGet() {
        String accept = request.getHeader("Accept");
        return new ResponseEntity<Void>(HttpStatus.NOT_IMPLEMENTED);
    }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

遇到问题

生成代码后多出了一堆非服务端相关的代码，同时报某些依赖包不存在：

目录结构：

从目录结构可以看出来，这个是一个完整的springmvc项目，有对应的WebApplication配置。swagger除了生成代码外，还支持生成接口的描述文档，这里生成的代码可以直接作为一个项目启动，以web项目的方式作为接口描述手册。如果不想生成这些代码的话，在plugin设置中加上参数：

<generateSupportingFiles>false</generateSupportingFiles>
1

就不会生成API手册相关的文件了。