SpringBoot中整合Swagger2生成接口文档

为什么要用Swagger2?

在开发过程中为了减少平时与其他团队的频繁沟通成本,我们通常会创建一份RESTful API文档来记录所有接口的细节,但是这样做的话会有一些问题:

  1. 一个大型的项目往往会有超级多的接口,由于接口数量众多,而且细节比较复杂,高质量的把这份文档编写完成,本身就是一个超级困难的事情,下层编写文档的程序员们怨声不绝于耳。
  2. 随着时间的推移,会不断修改接口的实现,这个时候也就必须要修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象。

为了解决这些问题,给大家介绍一下RESTful API文档的重磅好伙伴Swagger2,它可以轻轻松松整合进Spring Boot中,并与Spring MVC程序配合组织出强大的RESTful API文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。
下面开始进行整合,首先在pom.xml中加入Swagger2的依赖:
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.6.1</version>
</dependency>

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.6.1</version>
</dependency>

接下来编写Swagger配置类,加上@Configuration注解,这个类的东西其实只需要了解具体能配置哪些东西就行了,毕竟这个类配置一次以后就不再改了。需要注意的是里面是配置了Controller包的路径,不然扫描不到接口。

package com.test.swagger.demo;

import org.springframework.context.annotation.Bean;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @Auther: 马旭辉
 * @Date: 2019/4/27 14:49
 * @Description: Swagger2配置类
 */
@Configuration
public class SwaggerConfig {
    public class Swagger2 {

        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.test.swagger.demo.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
		//用来创建该Api的基本信息
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Swagger2构建api文档")
                    .description("说明文字XXX")
                    .termsOfServiceUrl("https://www.csdn.net/")
                    .version("1.0")
                    .build();
        }
    }
}

在Spring Boot的启动类上加入注解@EnableSwagger2,表示开启Swagger。

@SpringBootApplication
@EnableSwagger2
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

}

下一步是编写Restful接口,在这之前我们先建立一个实体类:

public class User implements Serializable{
    private int id;
    private String name;
    private int age;
    //此处省略 Getter和 Setter方法
}
package com.test.swagger.demo.controller;

import com.test.swagger.demo.bean.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
import java.util.HashMap;

/**
 * @Auther: 马旭辉
 * @Date: 2019/4/27 15:14
 * @Description:
 */
@RestController
public class UserController {
    //创建一个Map用来存储User对象,模拟数据库操作
    static HashMap<Integer, User> userHashMap = new HashMap<>();

    //往Map里塞入一些数据
    static {
        userHashMap.put(1, new User(1, "蔡徐坤", 26));
        userHashMap.put(2, new User(2, "吴亦凡", 24));
        userHashMap.put(3, new User(3, "孙悟空", 344));
        userHashMap.put(4, new User(4, "二师兄", 119));
    }

    @ApiOperation(value = "获取用户信息", notes = "根据id获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
    @GetMapping("user/{id}")
    public User getUserById(@PathVariable Integer id) {
        User user = userHashMap.get(id);//查询数据
        //返回数据
        return user;
    }
}

启动项目,访问 http://localhost:8080/swagger-ui.html
在这里插入图片描述
看到这个页面说明成功进入了Swagger2,这里会显示我们添加的描述文字,然后我们输入一个1进行测试一下:
在这里插入图片描述
很明显这个接口测试成功了,已经显示出来了查询结果:
在这里插入图片描述
项目结构如下:
在这里插入图片描述
最后说一下Swagger2的注解,Swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等:

  • @Api:修饰整个类,描述Controller的作用
  • @ApiOperation:描述一个类的一个方法,或者说一个接口
  • @ApiParam:单个参数描述
  • @ApiModel:用对象来接收参数
  • @ApiProperty:用对象接收参数时,描述对象的一个字段
  • @ApiResponse:HTTP响应其中1个描述
  • @ApiResponses:HTTP响应整体描述
  • @ApiIgnore:使用该注解忽略这个API
  • @ApiError :发生错误返回的信息
  • @ApiImplicitParam:一个请求参数
  • @ApiImplicitParams:多个请求参数

欢迎关注微信公众号"程序员小辉"

微信图片20190813101011.jpg

  • 1
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 1
    评论
评论 1
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

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

抵扣说明:

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

余额充值