SpringBoot 集成Swagger2

 

1. Swagger2的介绍

Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，加上swagger-ui，可以有很好的呈现。 

2.   SpringBoot集成

1)  pom引入依赖jar包： 

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.1</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.1</version>
</dependency>

   2) 创建Swagger配置类

package com.example.springrootdemo.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration
@EnableSwagger2
public class SwaggerConfig {

    public Docket swaggerSpringMvcPlugin(){

      return  new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
    }

}

 3) 创建UserController

   

package com.example.springrootdemo.controller;

import com.example.springrootdemo.entity.Req_SysUser;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.omg.CORBA.INTERNAL;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/User")
@Api("用户业务逻辑")
public class UserController {


    @ApiOperation(value = "根据用户id查询用户信息",notes = "查询数据库中某个用户的信息")
    @ApiImplicitParam(name="id",value = "用户编号",paramType ="path",required = true,dataType = "long")
    @RequestMapping("/{id}")
    public Req_SysUser view(@PathVariable("id")long id) {
        Req_SysUser user = new Req_SysUser();
        user.setUsername("张三");
        user.setPassword("123213213");
        return  user;
    }

}

 

4)运行结果

 完成配置，启动SpringBoot程序，访问：http://localhost:8016/swagger-ui.html#/

 

 5）常用注解的使用与说明
@Api：一般用于Controller中,用于接口分组

@ApiOperation：接口说明,用于api方法上。

@ApiImplicitParams：用在方法上包含一组参数说明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

paramType：参数放在哪个地方

header 请求参数的获取：@RequestHeader

query 请求参数的获取：@RequestParam

path（用于restful接口） 请求参数的获取：@PathVariable

body（不常用）

form（不常用）

name：参数名

dataType：参数类型

required：参数是否必须传

value：参数的意思

defaultValue：参数的默认值

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

code：数字，例如400

message：信息，例如”请求参数没填好”

response：抛出异常的类

@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）表明这是一个被swagger框架管理的model，用于class上
@ApiModelProperty ：使用在实体类上的成员变量上，描述成员变量的含义。

   3.遇到问题

  1)  springboot整合swagger2，导入不了@EnableSwagger2注解？

解决办法：

   2） 通过pom.xml添加了jar包依赖，但是无法在Dependencies中看到？

     解决办法：Maven--project-Dependencies--刷新依赖，自动就会显示相应的jar包

    3） java.lang.NumberFormatException: For input string: 错误

解决方法：可以更改文件的日志记录级别，在application.properties或application.yml中执行此操作：

application.properties：

logging.level.io.swagger.models.parameters.AbstractSerializableParameter=error

application.yml：

logging:

level:

io.swagger.models.parameters.AbstractSerializableParameter: error