SpringBoot整合Swagger2实现自动生成API(含源码)

  1. 相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。

  2. 你只需要按照Swagger的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。

  3. 开发新版本或者迭代版本的时候,只需要更新Swagger描述文件,就可以自动生成接口文档和客户端服务端代码,做到调用端代码、服务端代码以及接口文档的一致性。

  4. 通过在项目中引入Swagger,可以扫描相关的代码,生成该描述文件,进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式,在后面需求持续迭代的项目中,显得尤为重要和高效。

  5. 下面介绍SpringBoot整合Swagger生成API文档的过程

  6. 新建一个SpringBoot工程springboot-swagger2

  7. 引入相关的Maven依赖

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- Swagger2依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <!-- Swagger2依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
        <!-- Mybatis依赖 -->
        <dependency>
            <groupId>org.mybatis.spring.boot</groupId>
            <artifactId>mybatis-spring-boot-starter</artifactId>
            <version>2.1.0</version>
        </dependency>
        <!-- druid依赖 -->
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>druid</artifactId>
            <version>1.1.10</version>
        </dependency>
        <!-- mysql依赖 -->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    
  8. 在数据库中建立测试的表,SQL脚本如下

    DROP TABLE IF EXISTS `t_user`;
    CREATE TABLE `t_user` (
      `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
      `username` varchar(255) NOT NULL,
      `password` varchar(255) DEFAULT NULL,
      `age` int(11) DEFAULT NULL,
      `birthday` datetime DEFAULT NULL,
      `comment` varchar(255) DEFAULT NULL,
      PRIMARY KEY (`id`)
    ) ENGINE=InnoDB AUTO_INCREMENT=4 DEFAULT CHARSET=utf8mb4;
    
  9. 新建Mybatis配置文件 resources\mybatis\config.xml

    <?xml version="1.0" encoding="UTF-8" ?>
    <!DOCTYPE configuration PUBLIC "-//mybatis.org//DTD Config 3.0//EN" "http://mybatis.org/dtd/mybatis-3-config.dtd">
    <configuration>
        <settings>
            <!--配置命名规则-->
            <setting name="mapUnderscoreToCamelCase" value="true" />
        </settings>
        <typeAliases>
            <typeAlias alias="Integer" type="java.lang.Integer" />
            <typeAlias alias="Long" type="java.lang.Long" />
            <typeAlias alias="HashMap" type="java.util.HashMap" />
            <typeAlias alias="LinkedHashMap" type="java.util.LinkedHashMap" />
            <typeAlias alias="ArrayList" type="java.util.ArrayList" />
            <typeAlias alias="LinkedList" type="java.util.LinkedList" />
        </typeAliases>
    </configuration>
    
  10. 修改配置文件application.properties为application.yml,并添加下面的配置项

    server:
      port: 8081
    
    spring:
      datasource:
        url: jdbc:mysql://localhost:3306/test?useSSL=false&serverTimezone=UTC
        username: root
        password: root
        driver-class-name: com.mysql.cj.jdbc.Driver
        type: com.alibaba.druid.pool.DruidDataSource
    
    mybatis:
      config-location: classpath:mybatis/config.xml
      mapper-locations: classpath*:mybatis/mapper/**/*.xml
    
  11. 新建Swagger2的配置类

    package com.kangswx.springbootswagger2.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    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;
    
    @Configuration
    public class Swagger2 {
    
        /**
         * 生成API对象
         * @return
         */
        @Bean
        public Docket createRestApi(){
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    //controller包的路径,生成controller对应的API文档
                    .apis(RequestHandlerSelectors .basePackage("com.kangswx.springbootswagger2.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        /**
         * 生成API描述信息
         * @return
         */
        public ApiInfo apiInfo(){
            return new ApiInfoBuilder()
                    .title("Spring整合Swagger2的API")
                    .description("简单优雅的rest风格,https://blog.csdn.net/kangswx")
                    .termsOfServiceUrl("https://blog.csdn.net/kangswx")
                    .version("1.0")
                    .build();
        }
    }
    
    
  12. 新建User的实体类

    import java.io.Serializable;
    import java.util.Date;
    
    public class User implements Serializable {
    
        private Integer id;
    
        private String username;
    
        private String password;
    
        private Integer age;
    
        private Date birthday;
    
        private String comment;
    
        public Integer getId() {
            return id;
        }
    
        public void setId(Integer id) {
            this.id = id;
        }
    
        public String getUsername() {
            return username;
        }
    
        public void setUsername(String username) {
            this.username = username == null ? null : username.trim();
        }
    
        public String getPassword() {
            return password;
        }
    
        public void setPassword(String password) {
            this.password = password == null ? null : password.trim();
        }
    
        public Integer getAge() {
            return age;
        }
    
        public void setAge(Integer age) {
            this.age = age;
        }
    
        public Date getBirthday() {
            return birthday;
        }
    
        public void setBirthday(Date birthday) {
            this.birthday = birthday;
        }
    
        public String getComment() {
            return comment;
        }
    
        public void setComment(String comment) {
            this.comment = comment == null ? null : comment.trim();
        }
    
    }
    
  13. 新增UserMapper接口

    import com.kangswx.springbootswagger2.entity.User;
    import org.apache.ibatis.annotations.Mapper;
    import org.springframework.stereotype.Repository;
    
    @Repository
    @Mapper
    public interface UserMapper {
    
        int deleteByPrimaryKey(Integer id);
    
        int insert(User record);
    
        int insertSelective(User record);
    
        User selectByPrimaryKey(Integer id);
    
        int updateByPrimaryKeySelective(User record);
    
        int updateByPrimaryKey(User record);
    
    }
    
  14. 新增UserMapper配置文件(resources\mybatis\mapper\UserMapper.xml)

    <?xml version="1.0" encoding="UTF-8" ?>
    <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd" >
    <mapper namespace="com.kangswx.springbootswagger2.mapper.UserMapper" >
      <resultMap id="BaseResultMap" type="com.kangswx.springbootswagger2.entity.User" >
        <id column="id" property="id" jdbcType="INTEGER" />
        <result column="username" property="username" jdbcType="VARCHAR" />
        <result column="password" property="password" jdbcType="VARCHAR" />
        <result column="age" property="age" jdbcType="INTEGER" />
        <result column="birthday" property="birthday" jdbcType="TIMESTAMP" />
        <result column="comment" property="comment" jdbcType="VARCHAR" />
      </resultMap>
    
      <sql id="Base_Column_List" >
        id, username, password, age, birthday, comment
      </sql>
    
      <select id="selectByPrimaryKey" resultMap="BaseResultMap" parameterType="java.lang.Integer" >
        select 
        <include refid="Base_Column_List" />
        from t_user
        where id = #{id,jdbcType=INTEGER}
      </select>
    
      <delete id="deleteByPrimaryKey" parameterType="java.lang.Integer" >
        delete from t_user
        where id = #{id,jdbcType=INTEGER}
      </delete>
    
      <insert id="insert" parameterType="com.kangswx.springbootswagger2.entity.User" >
        insert into t_user (id, username, password, 
          age, birthday, comment
          )
        values (#{id,jdbcType=INTEGER}, #{username,jdbcType=VARCHAR}, #{password,jdbcType=VARCHAR}, 
          #{age,jdbcType=INTEGER}, #{birthday,jdbcType=TIMESTAMP}, #{comment,jdbcType=VARCHAR}
          )
      </insert>
    
      <insert id="insertSelective" parameterType="com.kangswx.springbootswagger2.entity.User" >
        insert into t_user
        <trim prefix="(" suffix=")" suffixOverrides="," >
          <if test="id != null" >
            id,
          </if>
          <if test="username != null" >
            username,
          </if>
          <if test="password != null" >
            password,
          </if>
          <if test="age != null" >
            age,
          </if>
          <if test="birthday != null" >
            birthday,
          </if>
          <if test="comment != null" >
            comment,
          </if>
        </trim>
        <trim prefix="values (" suffix=")" suffixOverrides="," >
          <if test="id != null" >
            #{id,jdbcType=INTEGER},
          </if>
          <if test="username != null" >
            #{username,jdbcType=VARCHAR},
          </if>
          <if test="password != null" >
            #{password,jdbcType=VARCHAR},
          </if>
          <if test="age != null" >
            #{age,jdbcType=INTEGER},
          </if>
          <if test="birthday != null" >
            #{birthday,jdbcType=TIMESTAMP},
          </if>
          <if test="comment != null" >
            #{comment,jdbcType=VARCHAR},
          </if>
        </trim>
      </insert>
    
      <update id="updateByPrimaryKeySelective" parameterType="com.kangswx.springbootswagger2.entity.User" >
        update t_user
        <set >
          <if test="username != null" >
            username = #{username,jdbcType=VARCHAR},
          </if>
          <if test="password != null" >
            password = #{password,jdbcType=VARCHAR},
          </if>
          <if test="age != null" >
            age = #{age,jdbcType=INTEGER},
          </if>
          <if test="birthday != null" >
            birthday = #{birthday,jdbcType=TIMESTAMP},
          </if>
          <if test="comment != null" >
            comment = #{comment,jdbcType=VARCHAR},
          </if>
        </set>
        where id = #{id,jdbcType=INTEGER}
      </update>
    
      <update id="updateByPrimaryKey" parameterType="com.kangswx.springbootswagger2.entity.User" >
        update t_user
        set username = #{username,jdbcType=VARCHAR},
          password = #{password,jdbcType=VARCHAR},
          age = #{age,jdbcType=INTEGER},
          birthday = #{birthday,jdbcType=TIMESTAMP},
          comment = #{comment,jdbcType=VARCHAR}
        where id = #{id,jdbcType=INTEGER}
      </update>
    </mapper>
    
  15. 新增UserService接口

    import com.kangswx.springbootswagger2.entity.User;
    
    public interface UserService {
    
        User getByid(Integer id);
    
        int updateUser(User user);
    
        int deleteUserById(Integer id);
    
        int addUser(User user);
    }
    
  16. 新增UserServiceImpl实现类

    import com.kangswx.springbootswagger2.entity.User;
    import com.kangswx.springbootswagger2.mapper.UserMapper;
    import com.kangswx.springbootswagger2.service.UserService;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.stereotype.Service;
    
    @Service
    public class UserServiceImpl implements UserService {
    
        @Autowired
        private UserMapper userMapper;
    
        @Override
        public User getByid(Integer id) {
            return userMapper.selectByPrimaryKey(id);
        }
    
        @Override
        public int updateUser(User user) {
            return userMapper.updateByPrimaryKeySelective(user);
        }
    
        @Override
        public int deleteUserById(Integer id) {
            return userMapper.deleteByPrimaryKey(id);
        }
    
        @Override
        public int addUser(User user) {
            return userMapper.insert(user);
        }
    
    }
    
  17. 新增UserController,并为每个接口添加Swagger注解信息

    import com.kangswx.springbootswagger2.entity.JsonData;
    import com.kangswx.springbootswagger2.entity.User;
    import com.kangswx.springbootswagger2.service.UserService;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.*;
    
    @RestController
    @RequestMapping("/api/v1/user")
    public class UserController {
    
        @Autowired
        private UserService userService;
    
        /**
         * 查询接口
         * @param id
         * @return
         */
        //ApiOperation生成的接口的API描述信息
        @ApiOperation(value = "查询用户信息", notes = "根据url的id来查询用户详细信息")
        //ApiImplicitParam生成的接口参数的API描述信息
        @ApiImplicitParam(name="id", value = "用户的id", required = true, dataType = "int", paramType = "path")
        @GetMapping(value = "{id}")
        public Object getById(@PathVariable int id){
            User user = userService.getByid(id);
            return JsonData.buildSuccess(user);
        }
    
        /**
         * 修改接口
         * @param user
         * @return
         */
        //ApiOperation生成的接口的API描述信息
        @ApiOperation(value = "修改用户信息", notes = "根据传入对象的非空字段值和id修改用户信息")
        //ApiImplicitParam生成的接口参数的API描述信息
        @ApiImplicitParam(name = "user", value = "用户对象", required = true, dataType = "Json", paramType = "body")
        @PutMapping()
        public Object updateUserById(@RequestBody User user){
            int ret = userService.updateUser(user);
            JsonData jsonData = null;
            if(ret > 0){
                jsonData = JsonData.buildSuccess("修改成功");
            } else {
                jsonData = JsonData.buildError("修改失败");
            }
            return jsonData;
        }
    
        /**
         * 添加接口
         * @param user
         * @return
         */
        //ApiOperation生成的接口的API描述信息
        @ApiOperation(value = "新增用户", notes = "将传入的用户对象添加到数据库")
        //ApiImplicitParam生成的接口参数的API描述信息
        @ApiImplicitParam(name = "user", value = "用户对象", required = true, dataType = "Json", paramType = "body")
        @PostMapping()
        public Object addUser(@RequestBody User user){
            int ret = userService.addUser(user);
            JsonData jsonData = null;
            if(ret > 0){
                jsonData = JsonData.buildSuccess("添加成功");
            } else {
                jsonData = JsonData.buildError("添加失败");
            }
            return jsonData;
        }
    
        /**
         * 删除接口
         * @param id
         * @return
         */
        //ApiOperation生成的接口的API描述信息
        @ApiOperation(value = "删除用户", notes = "根据url的id来删除数据库中对应的用户")
        //ApiImplicitParam生成的接口参数的API描述信息
        @ApiImplicitParam(name="id", value = "用户的id", required = true, dataType = "int", paramType = "path")
        @DeleteMapping("{id}")
        public Object deleteUser(@PathVariable int id){
            int ret = userService.deleteUserById(id);
            JsonData jsonData = null;
            if(ret > 0){
                jsonData = JsonData.buildSuccess("删除成功");
            } else {
                jsonData = JsonData.buildError("删除失败");
            }
            return jsonData;
        }
    
    }
    
  18. 在启动类上添加MapperScan和EnableSwagger2的注解

    import org.mybatis.spring.annotation.MapperScan;
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @MapperScan(basePackages = "com.kangswx.springbootswagger2.mapper")
    @SpringBootApplication
    @EnableSwagger2     //启动Swagger2
    public class SpringbootSwagger2Application {
    
        public static void main(String[] args) {
            SpringApplication.run(SpringbootSwagger2Application.class, args);
        }
    
    }
    
  19. 启动SpringBoot项目,并访问 http://localhost:8081/swagger-ui.html

  20. 会看到Swagger生成的API文档

  21. 进行简单的测试,测试查询接口

    输入id的参数后,点击Try it out!就会看到查询的结果

  22. 测试添加

    点击Try it out!,返回结果为

  23. 测试删除

    返回结果为

  24. 至此,所有的功能测试正常, 上面的代码详见 SpringBoot整合Swagger2实现自动生成API

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

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

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

抵扣说明:

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

余额充值