SpringBoot - Swagger2的集成与使用教程(生成API接口文档)

SpringBoot - Swagger2的集成与使用教程(生成API接口文档)

 

    在前后端分离开发中,为了减少与其它团队的沟通成本,一般都会构建一份 RESTful API 文档来描述所有的接口信息。但传统的方式有许多弊端,不仅编写文档工作量巨大,而且维护不方便,测试也不方便(需要借助第三方工具,如 Postman 来测试)

    为解决这些问题,我们可以使用 Swagger 2 来构建在线接口文档,下面通过样例进行演示。

 

一、基本介绍

1,什么是 Swagger 2

    Swagger 2 是一个开源软件框架,可以帮助开发人员设计、构建、记录和使用 RESTful Web 服务,它将代码和文档融为一体,可以完美解决文档编写繁琐、维护不方便等问题。使得开发人员可以将大部分精力集中到业务中,而不是繁杂琐碎的文档中。

 

2,安装配置

(1)首先编辑项目的 pom.xml 文件,添加 Swagger 2 相关依赖: 

注意:因为我这里引入的 swagger ui 是 2.7 以上的版本,所以还需要引入 guava,否则会因为 guava 兼容性问题造成项目启动报错(无法启动)

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.9.2</version>

</dependency>

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger-ui</artifactId>

    <version>2.9.2</version>

</dependency>

<dependency>

    <groupId>com.google.guava</groupId>

    <artifactId>guava</artifactId>

    <version>20.0</version>

</dependency>


(2)接着创建 Swagger 2 的配置类,代码如下: 代码说明:

  • 首先通过 @EnableSwagger2 注解开启了 Swagger 2,然后最主要的是配置一个 Docket。
  • 通过 apis 方法配置要扫描的 controller 位置,通过 paths 方法配置路径。
  • 在 apiInfo 中构建文档的基本信息,例如描述、联系人信息、版本、标题等。

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

@Configuration

@EnableSwagger2

public class SwaggerConfig {

    @Bean

    Docket docket() {

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())

                .select()

                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))

                .paths(PathSelectors.any())

                .build();

    }

 

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

                .title("API测试文档")

                .description("DEMO项目的接口测试文档")

                .termsOfServiceUrl("http://www.hangge.com")

                .version("1.0")

                .contact(new Contact("航歌",

                        "http://www.hangge.com",

                        "hangge@hangge.com"))

                .build();

    }

}

 

二、使用样例

1,添加注解

(1)首先我们在 Controller 上添加相关的 @Api 注解:

(1)@Api 注解标注在类上用来描述整个 Controller 信息。
(2)@ApiOperation 注解标注在方法上,用来描述一个方法的基本信息。
(3)@ApiImplicitParam 注解标注在方法上,用来描述方法的参数。其中 paramType 是指方法参数的类型,有如下可选值:

  • path:参数获取方式为 @PathVariable
  • query:参数获取方式为 @RequestParam
  • header:参数获取方式为 @RequestHeader
  • body
  • form

(4)如果有多个参数,可以将多个参数的 @ApiImplicitParam 注解放到 @ApiImplicitParams 中。
(5)@ApiResponse 是对响应结果的描述。code 表示响应码,message 为相应的描述信息。如果有多个 @ApiResponse,则放在一个 @ApiResponses 中。
(6)@ApiIgnore 注解表示不对某个接口生成文档。

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

@RestController

@Api(tags = "用户数据接口")

public class UserController {

    @ApiOperation(value ="查询用户", notes = "根据 id 查询用户")

    @ApiImplicitParam(paramType = "path", name = "id", value = "用户 id", required = true)

    @GetMapping("/user/{id}")

    public String getUserById(@PathVariable Integer id){

        return "查找的用户id是:" + id;

    }

 

    @ApiOperation(value = "新增用户", notes = "根据传入的用户名和密码添加一个新用户")

    @ApiImplicitParams({

            @ApiImplicitParam(paramType = "query", name = "username",

                    value = "用户名", required = true, defaultValue = "test"),

            @ApiImplicitParam(paramType = "query", name = "password",

                    value = "密码", required = true, defaultValue = "123")

    })

    @PostMapping("/user")

    public String addUser(@RequestParam String username, @RequestParam String password) {

        return "新增用户:" + username + " " + password;

    }

 

    @ApiOperation(value = "删除用户", notes = "根据 id 删除用户")

    @ApiResponses({

            @ApiResponse(code = 200, message = "删除成功!"),

            @ApiResponse(code = 500, message = "删除失败!")

    })

    @DeleteMapping("/user/{id}")

    public Integer deleteUserById(@PathVariable Integer id) {

        return id;

    }

 

    @ApiOperation(value = "修改用户", notes = "传入用户信息进行更新修改")

    @PutMapping("/user")

    public String updateUser(@RequestBody User user){

        return user.toString();

    }

 

    @ApiIgnore

    @GetMapping("/user/test")

    public String test() {

        return "这是一个测试接口,不需要在api文档中显示。";

    }

}


(2)接着对模型对象也添加相关的注解:

    由于在上面 Controller 里的 updateUser 方法中,使用 @RequestBody 注解来接收数据,此时可以通过 @ApiModel 注解和 @ApiModelProperty 注解配置 User 对象的描述信息。

1

2

3

4

5

6

7

8

9

10

11

12

13

14

@Getter

@Setter

@ToString

@ApiModel(value = "用户实体类", description = "用户信息描述类")

public class User {

    @ApiModelProperty(value = "用户id")

    private Integer id;

 

    @ApiModelProperty(value = "用户名")

    private String username;

 

    @ApiModelProperty(value = "用户密码")

    private String password;

}

 

2,查看接口文档

(1)启动 Spring Boot 项目,在浏览器中输入 http://localhost:8080/swagger-ui.html 即可看到接口文档。

原文:SpringBoot - Swagger2的集成与使用教程(生成API接口文档)

 

(2)展开任意一个接口描述,单击 Try it out 按钮后,可以实现对该接口的测试。

 

附:使用 swagger-bootstrap-ui 代替原来的 ui

(1)如果觉得原先使用的 swagger ui 比较丑、或者不方便的话,可以试试 swagger-bootstrap-ui。只需修改 pom.xml 文件,将原来的 springfox-swagger-ui 依赖替换成  swagger-bootstrap-ui 即可。

注意:1.9.6 是 swagger-bootstrap-ui 的最后一个版本。由于各种原因,原作者又另起一新的项目:knife4j-spring-ui。knife4j 会包含 swagger-bootstrap-ui 的所有特性,并增加许多新特性,有兴趣的小伙伴可以尝试一下。

 

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.9.2</version>

</dependency>

<dependency>

    <groupId>com.github.xiaoymin</groupId>

    <artifactId>swagger-bootstrap-ui</artifactId>

    <version>1.9.6</version>

</dependency>

<dependency>

    <groupId>com.google.guava</groupId>

    <artifactId>guava</artifactId>

    <version>20.0</version>

</dependency>


(2)项目启动后,通过 http://localhost:8080/doc.html 地址即可访问新的 UI 界面:

原文:SpringBoot - Swagger2的集成与使用教程(生成API接口文档)

 

(3)可以看到 bootstrap 风格的界面样式比原先的清爽、高效许多:

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值