SpringBoot搭建Swagger2详细讲解及使用教程_springboot swagger2

       最近在项目开发中想单独调试或者运行某个接口的功能，特别是post方式直接访问时会出错的问题，因此想在项目中集成Swagger2框架，此时就可以对各个接口进行测试，下面开始代码分析及讲解：
（1）首先在pom.xml文件中引入Swagger2的相关依赖：

		<!-- Swagger依赖 -->
		<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>org.springframework.boot</groupId>
		    <artifactId>spring-boot-starter-web</artifactId>
		</dependency>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

（2）编写Swagger2的配置类：

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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration//配置SwaggerConfig类型在SpringBoot
@EnableSwagger2//
public class SwaggerConfig {

	@Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
				/*此处为你的访问层接口包路径，即控制层所对应的包路径，这里
				*如果没有编写正确，会造成的在访问swagger2页面时没有接口信息出现
				*/  
				 .apis(RequestHandlerSelectors.basePackage("com.gdupt.demo.security.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
               			 //标题
                        .title("基础框架系统开发文档API总览界面")
                        //描述
                        .description("基础框架系统接口详细信息......")
                        //版本号
                        .version("9.0")
                        //联系方式
                        .contact(new Contact("指尖上跳动的旋律","blog.csdn.net","xxx@qq.com"))
                        //许可证
                        .license("指尖上跳动的旋律")
                        //许可证访问链接
                        .licenseUrl("https://blog.csdn.net/xuguoxing123")
                        .build());
    }
}
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

（3）在类或控制层的方法名之上定义接口的名称和参数类型即可，具体代码如下：

import javax.servlet.http.HttpServletRequest;

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

@Api(tags = "登录管理入口")
@RestController
public class LoginController {

    @ApiOperation("用户登录验证")
	@ApiImplicitParams({
		@ApiImplicitParam(name = "username",value="用户名"),
		@ApiImplicitParam(name = "password",value="密码",defaultValue = "20", required = true)
	})
    @PostMapping("/login")
    public String login(String username,String password,HttpServletRequest request){
        String str = "用户名："+username+"密码："+password;
        return str ;
    }

    @ApiOperation("空内容测试接口")
	@ApiImplicitParam(name = "username",value="用户名")
    @PostMapping("test")
    public String test(){
        return "空内容测试接口"
    }
}
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

该步骤主要分三步：
①设置当前模块的接口文档标题
使用注解是：@Api(tags = “登录管理入口”)，该注解是标注在类的头部；

②设置当前接口的名称
使用的注解是： @ApiOperation(“用户登录验证”)，该注解是标注在方法名的头部；

③设置当前接口的参数
      参数设置分为单个参数和多个参数，所使用的注解分别是：
1）单个参数：
       @ApiImplicitParam(name = “username”,value=“用户名”)

2）多个参数
      @ApiImplicitParams({
              @ApiImplicitParam(name = “username”,value=“用户名”),
              @ApiImplicitParam(name = “password”,value=“密码”,defaultValue = “20”, required = true)
       })

该注解主要有四个比较常用的属性：
       name：是指前端输入框的标识变量，类似input标签的name属性，用于接收swagger2框架前端页面提交的值；
       value：是指当前参数的具体描述；
       defaultValue：当前参数的默认值；
       required：是否为必填，默认值为false；

       值得注意的是，如果我们想获取参数列表中的值，只需要在方法的参数列表中一一对应定义相关的变量，与注解的name属性对应，就可以获取前端提交过来的值。

（4）最后一步就是访问Sw agger2框架的首页，访问链接为：http://localhost:8080/swagger-ui.html#/，读者们可以根据自己的主机地址和项目端口号来修改再访问即可，具体效果图如下：

接下来我们可以打开登录管理入口，按照如下操作：

输入文本框的信息，并且点击下面的按钮：

最后得出以下结果说明测试正确无误：

       如需要了解在SpringSecurity中集成Swagger2框架，可以点击此处链接进行查看：SpringSecurity中集成Swagger2框架。