Spring Cloud 整合 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通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

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

作用范围	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