1、Swagger产生的原因
自javaweb开发前后端分离之后，就产生了前后端接口对接的问题，通过以往的方式，接口对接具有复杂性，难维护性，逐渐成为程序员们难以解决的问题。为了解决这个问题，就生成了Swagger Specification（Swagger 规范），规定了如何对 API 的信息进行正确描述。
Swagger 规范本身是与编程语言无关的，它支持两种语法风格：JSON、YML
2、SpringBoot 集成 Swagger2
步骤：
1. 导入Swagger的jar包
<!-- Swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- 文档 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
<exclusion>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.21</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.8.5</version>
</dependency>
2. 添加配置文件
/** bootstrap ui : http://localhost:8080/doc.html
* 老版本界面 ： http://localhost:8080/swagger-ui.html
*
*
* @author llj
* @Title: 程序Lei
* @date 2021/5/20 13:16
*/
@SpringBootConfiguration
@EnableSwagger2
public class SwaggerConfig {
/**
* 在完成上述配置之后，其实就已经可以产生帮助文档了，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生。
* 对用户体验不好，我们通常需要自己增加一些说明来丰富文档内容。如果：
* 加入
*
* @ApiIgnore 忽略暴露的 api
* @ApiOperation(value = "查找", notes = "根据用户 ID 查找用户")
* 添加说明
* <p>
* <p>
* 其他注解：
* @Api ：用在类上，说明该类的作用
* @ApiImplicitParams ：用在方法上包含一组参数说明
* @ApiResponses ：用于表示一组响应
* 完成上述之后，启动springboot程序，
* 旧访问：http://localhost:8080/swagger-ui.html
* 新访问：http://localhost:8080/doc.html
* @ApiOperation() 用于方法；表示一个http请求的操作
* value用于方法描述
* notes用于提示内容
* tags可以重新分组（视情况而用）
* @ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
* name–参数名
* value–参数说明
* required–是否必填
* @ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收
* value–表示对象名
* description–描述
* 都可省略
* @ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改
* value–字段说明
* name–重写属性名字
* dataType–重写属性类型
* required–是否必填
* example–举例说明
* hidden–隐藏
* @ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上 比较简单, 这里不做举例
* @ApiImplicitParam() 用于方法
* 表示单独的请求参数
* @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
* name–参数ming
* value–参数说明
* dataType–数据类型
* paramType–参数类型
* example–举例说明
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(getApiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.llj.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo getApiInfo() {
return new ApiInfoBuilder()
.title("程序lei-APP项目数据接口")
.description("程序lei-APP项目数据接口，在线体验文档")
.termsOfServiceUrl("https://www.baidu.com")
.contact("雷诺")
.version("1.0")
.build();
}
}
** 这里一定要修改自己的包路径 .apis(RequestHandlerSelectors.basePackage(“com.llj.controller”))**
- 添加相关代码，并添加Swagger注解
controller包下：
@RestController
@RequestMapping("/swagger")
//@Api用与类上，tags：描述类的作用
@Api(tags = "测试swagger")
public class SwaggerController {
//@ApiOperation用于方法上，说明方法的作用， value： 主要描述 ， notes： 备注
@ApiOperation(value = "保存用户方法",notes = "保存100个用户")
// @ApiImplicitParams ({@ApiImplicitParam }) 用于方法上表示内部参数的信息，name 属性， value 描述， required 是否必填， //paramtype 参数类型
@ApiImplicitParams({
@ApiImplicitParam(name="name",value="姓名",required = true,paramType = "form"),
@ApiImplicitParam(name="age",value="年龄",required = true,paramType = "form",dataType = "Integer"),
@ApiImplicitParam(name="sex",value="性别",required = true,paramType = "form",dataType = "Integer"),
@ApiImplicitParam(name="Info",value="信息")
})
// @ApiResponses ({@ApiImplicitParam}) 用于方法上，描述服务区相应的状态， code 状态码 ，message 描述信息
@ApiResponses({
@ApiResponse(code = 200,message = "成功返回"),
@ApiResponse(code = 400,message = "找不到小宝贝了"),
@ApiResponse(code = 500,message = "后台出现了问题")
})
@RequestMapping("/save")
public List<User> test(){
List<User> list = new ArrayList<>();
for(int i = 0; i < 100; i++){
User user = new User();
user.setName("程序员_" + i);
user.setAge(i);
user.setSex(i/10);
user.setInfo("abcdefg" + i + "safsafs");
list.add(user);
}
return list;
}
@ApiImplicitParams({
@ApiImplicitParam(name="name",value="姓名",required = true,paramType = "form"),
@ApiImplicitParam(name="age",value="年龄",required = true,paramType = "form",dataType = "Integer"),
@ApiImplicitParam(name="sex",value="性别",required = true,paramType = "form",dataType = "Integer"),
@ApiImplicitParam(name="Info",value="姓名")
})
@RequestMapping("/login")
@ApiOperation(value = "用户登录",notes = "简单的一个人的添加")
public String login(@RequestParam String name,@RequestParam Integer age,@RequestParam Integer sex,@RequestParam String Info){
User user = new User();
user.setInfo(Info);
user.setSex(sex);
user.setAge(age);
user.setName(name);
return "已添加 : " + name + " 用户";
}
}
entity：实体类
@Data
@AllArgsConstructor
@NoArgsConstructor
@ToString
@Component
//@ApiModel 用在javabean的类上，描述javabean类
@ApiModel
public class User {
//@ApiModelProperty 用在属性参数上 value 描述参数 ， requied 表示参数是否必填
@ApiModelProperty(value = "用户名称name",required = true)
private String name;
@ApiModelProperty(value = "用户年龄age")
private Integer age;
@ApiModelProperty(value = "性别sex")
private Integer sex;
@ApiModelProperty(value = "信息info")
private String Info;
}
代码注解中有常用的用法注释
3、查看结果
两种方式查看：
- ** bootstrap ui : http://localhost:8080/doc.html**
- ** 老版本界面 ： http://localhost:8080/swagger-ui.html**
http://localhost:8080/doc.html：
http://localhost:8080/swagger-ui.html：
扫一扫
1310
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
