SpringBoot项目使用Swagger2(丝袜哥)实现接口测试管理

Posted 2020-12-18 Agoly

案例如下：

安装步骤，在写完的项目中，添加swagger的相关依赖

使用官方依赖

1、在pom.xml文件中添加swagger相关依赖

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

也可以：

　　　　 <properties>
    　　　　<!--swagger 版本 -->
    　　　　<swagger.version>2.7.0</swagger.version>
　　　　 </properties>

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

第一个是API获取的包，第二是官方给出的一个ui界面。这个界面可以自定义，默认是官方的，对于安全问题，以及ui路由设置需要着重思考。

2、swagger的configuration

需要特别注意的是swagger scan base package,这是扫描注解的配置，即你的API接口位置。

package cn.xnol.user;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


//swagger2的配置文件，在项目的启动类的同级文件建立
@Configuration
@EnableSwagger2
//是否开启swagger，正式环境一般是需要关闭的（避免不必要的漏洞暴露！），可根据springboot的多环境配置进行设置
@ConditionalOnProperty(name = "swagger.enable",  havingValue = "true")
public class Swagger2 {
    // swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 为当前包路径
                .apis(RequestHandlerSelectors.basePackage("cn.xnol.user.controller")).paths(PathSelectors.any())
                .build();
                //.pathMapping("/stu"); // 在这里可以设置请求的统一前缀
    }
    // 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 页面标题
                .title("SpringBoot基于Swagger2构建RESTful API接口测试")
                // 描述
                .description("API接口描述")
                // 创建人信息
                .contact(new Contact("Agoly", "https://www.cnblogs.com/qmfsun/", ""))
                // 版本号
                .version("1.0")
                .build();
    }
}

 

swagger.enable=true
springfox.documentation.swagger.v2.path = /user/api-docs

在controller中的接口路由中添加接口说明信息

package cn.xnol.user.controller;

import cn.xnol.user.entry.User;
import cn.xnol.user.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.Page;
import org.springframework.web.bind.annotation.*;

import javax.servlet.http.HttpServletResponse;
import java.util.List;

// 用于类；表示标识这个类是swagger的资源
//tags:说明，如果有多个tags,则会以list形式展示
//value: 说明，可以使用tags替代
@Api(value = "测试Controller" , tags = "用户服务")
@RestController
@RequestMapping("/user")
public class UserController {

    @Autowired
    UserService userService;

    /**
     * 添加学生
     * @param user 要添加的用户对象
     * @return
     */
    @ApiOperation(value="新增用户")
    @PostMapping("/add")
    public User save(User user){

        return userService.save(user);
    }

    /**
     * 修改学生
     * @param user
     * @return
     */
    @ApiOperation(value = "修改用户", notes = "修改用户信息")
    @PostMapping("/update")
    public User update(User user){
        return userService.save(user);
    }

    /**
     * 删除用户
     * @param id 要删除的用户id
     * @return
     */
    @ApiOperation(value = "根据id删除用户", notes = "删除用户")
    @GetMapping("/del/{id}")
    public String del(@PathVariable int id){
        userService.delete(id);
        return "yes";
    }

    /**
     * 通过姓名找到信息
     * @param name
     * @return
     */
    @ApiOperation(value = "根据用户名查询", notes="用户名查询")
    @GetMapping("/findByName/{name}")
    public List<User> findByName(@PathVariable String name){

        return userService.findUserByName(name);
    }

    /**
     * 利用分页查找全部信息
     * @param page
     * @param response
     * @return
     */
    @ApiOperation(value = "分页查询", notes="默认5条记录显示页")
    @GetMapping("/query")
    public Page<User> findByPage(Integer page, HttpServletResponse response){

        //异步请求使用
        response.setHeader("Access-Control-Allow-Origin","*");
        if(page==null || page<=0){
            page = 0;
        }else{
            page -= 1;
        }
        return userService.findAll(page,5);
    }

}

配置完成，启动项目，效果如下：

http://localhost:8080/api/swagger-ui.html

参考：

https://www.jianshu.com/p/49afc7465ce5

https://www.jianshu.com/p/be1e772b089a

https://www.cnblogs.com/zs-notes/p/10845741.html

https://blog.csdn.net/saytime/article/details/74937664

https://blog.csdn.net/fengyang182/article/details/106635760