本文共 2794 字，大约阅读时间需要 9 分钟。

springBoot项目整合Swagger2

swagger版本号：2.9.2

swagger是什么

  官方说法：Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步

  目前小咸儿做的项目是前后端分离的，为了更好的进行调试，所以后端需要提供一个API接口文档，这样开发起来更加的方便快捷。

springBoot和swagger进行整合

第一步：在pom.xml文件中引入jar包

         
    
     io.springfox
          
    
     springfox-swagger2
          
    
     2.9.2
     
    
         
    
     io.springfox
          
    
     springfox-swagger-ui
          
    
     2.9.2
     
    
         
    
     io.swagger
          
    
     swagger-annotations
          
    
     1.5.19
      
   

第二步：配置swagger

  新建一个配置文件swagger2，可以放在和controller包同等级的配置包中。

package com.miaoshaproject.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;import springfox.documentation.swagger2.annotations.EnableSwagger2;/** * swagger的配置信息 * @author Phyllis * @date 2019年7月25日09:23:13 */@Configuration@EnableSwagger2public class Swagger2 {
       @Bean    public Docket createRestApi() {
           return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                .select()                .apis(RequestHandlerSelectors.basePackage("com.miaoshaproject.controller"))                .paths(PathSelectors.any())                .build();    }    private ApiInfo apiInfo() {
           return new ApiInfoBuilder()                .title("miaosha APIs")                .description("")                .termsOfServiceUrl("")                .version("1.0")                .build();    }}

注解

  接下来就该在controller层中写入注解

• 首先需要在类上加入@RestController注解，这里的@RestController和@Controller可是不同的，@RestController=@Controller+@ResponseBody
• 还需要添加上@Api(tags = {“用户信息接口”})

  接着就可以在方法上添加注解了

• @ApiOperation() 用于方法；表示一个http请求的操作
• value用于方法描述 notes用于提示内容 tags可以重新分组（视情况而用）

示例：

@ApiOperation(value = "用户注册",notes = "根据用户信息进行用户注册")

  在方法中的参数上添加注解

• @ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
• name–参数名 value–参数说明 required–是否必填

示例：

public User getUserInfo(@ApiParam(name="id",value="用户id",required=true) Long id,@ApiParam(name="username",value="用户名") String username) {
            //业务逻辑忽略}

项目启动

问题

  一开始小咸儿整合的时候，只要Swagger的版本高于2.7.0以上，再启动项目后就不显示swagger页面，只显示如上图所示，但是也不报错，经过种种的排错以及尝试各种解决方法之后，最终发现有两个原因：

• 1、是没有导入swagger-annotations jar包
• 2、是在controller层使用的是@Controller，一开始没懂@RestController和@Controller的区别，后来明白@RestController=@Controller+@ResponseBody

  至于为什么小咸儿没有将就使用2.7.0版本的，一个是因为那个版本的swagger页面实在是不好看，二是不将就是发现问题的原动力，果然发现问题就解决问题了。

转载地址：http://pjerb.baihongyu.com/