版本一定要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