Spring boot整合 Swagger2 以及遇到的坑

一、引入依赖:

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

注意了注意了知识点! 

版本一定要2.5.0以及以上版本! 网上博文大多数引的2.2.2版本的, 这个版本在demo中没有问题, 但是开发中你肯定会引别的插件.

2.2.2版本的与feign有冲突! 会报bean创建加载异常!  这是个坑不想网友们再遇到同样的错误.

-----------------------------------------------------------------------------------------------

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

/**
* @ClassName: swagger2配置
* @Description: TODO
* @author 刘圈圈
* @date 2018年7月5日
*/

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("io.sr.modules.tra.app"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("旅游用车  APIs")
                .description("--------------------------------")
                .termsOfServiceUrl("https://blog.csdn.net/ityqing")
                .contact("刘圈圈")
                .version("0.1.1")
                .build();
    }

}

这个类要和启动类放在同一个目录下, 

用@Configuration注解该类,等价于XML中配置beans;用@Bean标注方法等价于XML中配置bean。

Application.class 加上注解@EnableSwagger2 表示开启Swagger,也可以在配置文件上加@EnableSwagger2

-----------------------------------------------------------------------------------------------

我的包结构:

.apis(RequestHandlerSelectors.basePackage("io.sr.modules.tra.app"))  : 是设置扫描的包路径

io.sr.modules.tra.app 它是模糊匹配的,所以我们在创建包还有URL时要避免这种格式

result接口:

这一步不是必要的, 只要swagger扫描到@RestController注解的类就会按默认配置生成接口文档

三、controller代码:

@RestController
@RequestMapping("/user")
@Api(value = "Shop")
public class SpringBootController {
 
    @ApiOperation(value = "获取helloWorld", notes = "简单SpringMVC请求")
    @RequestMapping("/")
    String home() {
        return "HELLO WORLD";
    }
 
    @ApiOperation(value = "获得A+B", notes = "根据url的classNo和url的studentName获得请求参数的字符串相加,RestFul风格的请求")
    @ApiImplicitParams({@ApiImplicitParam(name = "classNo", value = "班级编号", required = true, dataType = "String"),
    })
    @RequestMapping(value = "/class/{classNo}/to/{studentName}", method = RequestMethod.GET)
    String world(@PathVariable("classNo") String classNo, @PathVariable("studentName") String studentName) {
        return classNo + "  " + studentName;
    }
 
 
}

访问:http://localhost:8080/swagger-ui.html#/:

四、Swagger注解

swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。

 Controller注解

  • @Api:修饰整个类,描述Controller的作用
  • @ApiOperation:描述一个类的一个方法,或者说一个接口
  • @ApiParam:单个参数描述
  • @ApiImplicitParam:一个请求参数
  • @ApiImplicitParams:多个请求参数
  • @ApiProperty:用对象接收参数时,描述对象的一个字段
  • @ApiResponse:HTTP响应其中1个描述
  • @ApiResponses:HTTP响应整体描述
  • @ApiIgnore:使用该注解忽略这个API
  • @ApiError :发生错误返回的信息

JavaBean注解

@ApiModel:用对象来接收参数(Javabean 类上的注解)

@ApiModelProperty 作用在javabean的属性上(基本数据类型,自定义数据类型都可)

作用范围API使用位置
对象属性@ApiModelProperty用在出入参数对象的字段上
协议集描述@Api用于controller类上
协议描述@ApiOperation用在controller的方法上
Response集@ApiResponses用在controller的方法上
Response@ApiResponse用在 @ApiResponses里边
非对象参数集@ApiImplicitParams用在controller的方法上
非对象参数描述@ApiImplicitParam用在@ApiImplicitParams的方法里边
描述返回对象的意义@ApiModel用在返回对象类上

@RequestMapping此注解的推荐配置 
value 
method 
produces

示例:

    @ApiOperation("信息软删除")
    @ApiResponses({ @ApiResponse(code = CommonStatus.OK, message = "操作成功"),
            @ApiResponse(code = CommonStatus.EXCEPTION, message = "服务器内部异常"),
            @ApiResponse(code = CommonStatus.FORBIDDEN, message = "权限不足") })
    @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "Long", name = "id", value = "信息id", required = true) })
    @RequestMapping(value = "/remove.json", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public RestfulProtocol remove(Long id) {
    @ApiModelProperty(value = "标题")
    private String  title;

@ApiImplicitParam

属性取值作用
paramType查询参数类型
path以地址的形式提交数据
query直接跟参数完成自动映射赋值
body以流的形式提交 仅支持POST
header参数在request headers 里边提交
form以form表单的形式提交 仅支持POST
dataType参数的数据类型 只作为标志说明,并没有实际验证
Long
String
name接收参数名
value接收参数的意义描述
required参数是否必填
true必填
false非必填
defaultValue默认值

paramType 示例详解

path

 @RequestMapping(value = "/findById1/{id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)

 @PathVariable(name = "id") Long id

body

  @ApiImplicitParams({ @ApiImplicitParam(paramType = "body", dataType = "MessageParam", name = "param", value = "信息参数", required = true) })
  @RequestMapping(value = "/findById3", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE)

  @RequestBody MessageParam param

  提交的参数是这个对象的一个json,然后会自动解析到对应的字段上去,也可以通过流的形式接收当前的请求数据,但是这个和上面的接收方式仅能使用一个(用@RequestBody之后流就会关闭了)

header

  @ApiImplicitParams({ @ApiImplicitParam(paramType = "header", dataType = "Long", name = "id", value = "信息id", required = true) }) 

   String idstr = request.getHeader("id");
        if (StringUtils.isNumeric(idstr)) {
            id = Long.parseLong(idstr);
        }

Form

@ApiImplicitParams({ @ApiImplicitParam(paramType = "form", dataType = "Long", name = "id", value = "信息id", required = true) })
 @RequestMapping(value = "/findById5", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)

详细用法:  https://www.cnblogs.com/softidea/p/6251249.html 

与Spring Security整合设置密码 :  https://blog.csdn.net/rickiyeat/article/details/72639596

代码: https://gitee.com/didispace/swagger-butler


版权声明:本文为ityqing原创文章,遵循CC 4.0 BY-SA版权协议,转载请附上原文出处链接和本声明。