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

灰太狼 2021-09-24 15:22 444阅读 0赞

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

<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>

（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());
        }
    }

（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 "空内容测试接口"
        }
    }

该步骤主要分三步：  
**①设置当前模块的接口文档标题**  
使用注解是：**@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\#**/，读者们可以根据自己的**主机地址**和**项目端口号**来修改再访问即可，具体效果图如下：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3h1Z3VveGluZzEyMw_size_16_color_FFFFFF_t_70_pic_center]  
接下来我们可以打开登录管理入口，按照如下操作：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3h1Z3VveGluZzEyMw_size_16_color_FFFFFF_t_70_pic_center 1]  
输入文本框的信息，并且点击下面的按钮：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3h1Z3VveGluZzEyMw_size_16_color_FFFFFF_t_70_pic_center 2]  
最后得出以下结果说明测试正确无误：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3h1Z3VveGluZzEyMw_size_16_color_FFFFFF_t_70_pic_center 3]  
       如需要了解在SpringSecurity中集成Swagger2框架，可以点击此处链接进行查看：[SpringSecurity中集成Swagger2框架][SpringSecurity_Swagger2]。

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3h1Z3VveGluZzEyMw_size_16_color_FFFFFF_t_70_pic_center]: /images/20210923/3d4ebef0357f40bebbf6a62e11a38eaa.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3h1Z3VveGluZzEyMw_size_16_color_FFFFFF_t_70_pic_center 1]: /images/20210923/872eabb4ab8745de9a5b9c7dae7850c3.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3h1Z3VveGluZzEyMw_size_16_color_FFFFFF_t_70_pic_center 2]: /images/20210923/60b06b81df924be590f8e359a4b1e16e.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3h1Z3VveGluZzEyMw_size_16_color_FFFFFF_t_70_pic_center 3]: /images/20210923/7438e969b95f4d0a842654b04063403a.png
[SpringSecurity_Swagger2]: https://blog.csdn.net/xuguoxing123/article/details/108358799