SpringBoot整合Swagger2（完整版）

时间 2020-04-11 标签 springboot 整合 swagger2 swagger 完整

写在前面：从2018年末开始学习SpringBoot，也用SpringBoot写过一些项目。这里对学习Springboot的一些知识总结记录一下。若是你也在学习SpringBoot，能够关注我，一块儿学习，一块儿进步。html

文章目录

Swagger简介

Springboot整合Swagger

Swagger简介

一、为何要用Swagger

在平时开发中，一个好的API文档能够减小大量的沟通成本，还能够帮助新加入项目的同事快速上手业务。你们都知道平时开发时，接口变化老是不少，有了变化就要去维护，也是一件比较头大的事情。尤为是如今先后端分离状况，更容易形成文档和代码不一致。这时，咱们能够经过Swagger2来使接口规范，方便维护。web

二、Swagger简介

Swagger是一款Restful接口的文档在线自动生成和功能测试功能软件。
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的Web服务。整体目标是使客户端和文件系统做为服务器以一样的速度来更新文件的方法，参数和模型紧密集成到服务器端的代码，容许API来始终保持同步。spring

Springboot整合Swagger

一、项目结构

二、Swagger依赖

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

三、Swagger配置文件

import org.springframework.beans.factory.annotation.Value;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 1. swagger配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                //.enable(false)
                .select()
                //扫描的路径包,设置basePackage会将包下的全部被@Api标记类的全部方法做为api
                .apis(RequestHandlerSelectors.basePackage("com.mcy.springbootswagger.controller"))
                //指定路径处理PathSelectors.any()表明全部的路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title("SpringBoot中使用Swagger2接口规范")
                //文档描述
                .description("接口说明")
                //服务条款URL
                .termsOfServiceUrl("http://localhost:8080/")
                //版本号
                .version("1.0.0")
                .build();
    }
}

【注】@Configuration注解，配置文件，就很少解释了。@EnableSwagger2的做用是启用Swagger2相关功能。
Docket对象包含三个方面信息：
2. 整个API的描述信息，即ApiInfo对象包括的信息，这部分信息会在页面上展现。
3. 指定生成API文档的包名。
4. 指定生成API的路径。后端

四、测试控制器

import com.mcy.springbootswagger.User.User;
import com.mcy.springbootswagger.service.UserService;
import io.swagger.annotations.Api;
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("/user")
//说明接口文件
@Api(value = "测试接口", tags = "用户管理相关的接口", description = "用户测试接口")
public class UserController {
    @Autowired
    private UserService userService;

    /**
     * 保存数据
     * @param user
     * @return
     */
    @PostMapping(value = "/save")
    //方法参数说明，name参数名；value参数说明，备注；dataType参数类型；required 是否必传；defaultValue 默认值
    @ApiImplicitParam(name = "user", value = "新增用户数据")
    //说明是什么方法(能够理解为方法注释)
    @ApiOperation(value = "添加用户", notes = "添加用户")
    public String saveUser(User user){
        userService.save(user);
        return "保存成功";
    }

    /**
     * 根据id查询用户
     * @param id
     * @return
     */
    @GetMapping(value = "findById")
    @ApiOperation(value = "根据id获取用户信息", notes = "根据id查询用户信息")
    public User getUser(Integer id){
        return userService.findById(id);
    }

    @DeleteMapping(value = "deleteById")
    @ApiOperation(value = "根据id删除数据", notes = "删除用户")
    public String delete(Integer id){
        userService.deleteById(id);
        return "删除成功";
    }
}

【注】上述代码注解的含义注释已经写的很清楚了，这里就很少解释了。其中Service层中的代码就是对数据的操做，就很少说了。api

五、Swagger页面访问

运行项目，输入http://localhost:8080/swagger-ui.html访问Swagger页面，页面以下：

点击须要测试的接口方法，如图：

能够看到接口须要的参数，请求地址及接口说明信息。点击右上角的Try it out便可对接口进行测试。

查询结果：

这里这些了部分接口进行测试，能够根据项目需求自行添加其余接口。springboot

六、SpringSecurity中配置

若是Spring Boot项目中集成了Spring Security，接口会被拦截，须要在Spring Security的配置类中重写configure方法，对接口进行过滤一下。代码以下：服务器

@Override
public void configure(WebSecurity web) throws Exception {
    web.ignoring()
            .antMatchers("/swagger-ui.html")
            .antMatchers("/v2/**")
            .antMatchers("/swagger-resources/**");
}

最后有什么不足之处，欢迎你们指出，期待与你的交流。app