一、引入依赖:
-
<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;
| 属性 | 取值 | 作用 |
|---|---|---|
| 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
扫一扫
3165
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
