1. Maven依赖
首先,导入相关依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2. Swagger配置
其次,对Swagger进行一些简单的配置
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
//初始化并返回一个API选择构造器
.select()
// 扫描所有有注解的api
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 扫描所有 .apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
//创建该API的基本信息
.build().apiInfo(new ApiInfoBuilder()
.title("your title")
.description("your description")
.version("your version")
.contact(new Contact("your name","your blogUrl","your email"))
.license("your License")
.licenseUrl("your licenseUrl")
.build());
}
}
- @Configuration:定义配置类
- @EnableSwagger2:启用Swagger2
3. 演示代码
-
实体类:
import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; @ApiModel(value = "用户",description = "用户的实体类") public class User { @ApiModelProperty(value = "用户id") private Integer id; @ApiModelProperty(value = "用户名") private String username; @ApiModelProperty(value = "用户地址") private String address; //此处省略了Setter and Getter }
@ApiModel():用于实体类
- value:表示对象名
- description:描述
@ApiModelProperty():用于实体类字段
- value:字段说明
- name:重写属性名字
- dataType:重写属性类型
- required:是否必填
- example:举例说明
- hidden:隐藏
然后打开 http://localhost:8080/swagger-ui.html#/,地址根据自己的实际运行环境决定。
可以看到相关的Models的信息
-
UserController类:
import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.*; @RestController @Api(tags = "用户管理接口") @RequestMapping("/user") public class UserController { @PostMapping("/addUser") @ApiOperation("添加用户") @ApiImplicitParams({ @ApiImplicitParam(name = "username", value = "用户名", defaultValue = "轻舟",required = true), @ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "南宁", required = true) } ) public String addUser(@RequestParam(required = true) String username, @RequestParam(required = true) String address) { return "addUser success!"; } @GetMapping("/{id}") @ApiOperation("根据id查询用户") @ApiImplicitParam(name = "id", value = "用户id", defaultValue = "1", required = true) public User getUserById(@PathVariable Integer id) { User user = new User(); user.setId(1); user.setUsername("轻舟"); user.setAddress("杭州"); return user; } @PutMapping("/{id}") @ApiOperation("根据id更新用户") @ApiImplicitParam(name = "id", value = "用户id", defaultValue = "2", required = true) public Integer updateUserById(@PathVariable Integer id) { return 1; } }
@Api():用于类,标识此类为Swagger的资源
- tags:分组说明标签
@ApiOperation():用于方法
- value:方法的描述
- notes:提示内容
@ApiImplicitParam(): 用于方法
- name:方法的参数名
- value:参数的说明
- dataType:数据类型
- paramType:参数类型
- defaultValue:参数默认值
- required:参数是否为必须
- example:举例说明
@ApiIgnore()用于类或者方法上,可以不被Swagger显示在页面上
此时我们到Swagger页面上看,有以下的结果
以上就是对Swagger2的简单整合了,作为本人的学习笔记,仅供参考。
如有错误,还望指正。