SpringBoot整合Swagger2
Swagger2
在前端还没写好时,我们想进行后台测试数据时,比如传入值到后台或者显示后台的结果到页面,这时我们可以使用 Postman或者Swagger2来进行测试。
swagger是什么
1、是一款让你更好的书写API文档的规范且完整框架。
2、提供描述、生产、消费和可视化RESTful Web Service。
3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。
这里使用Swagger2在Springboot上进行简单的使用
依赖
<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> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>
第一个是API获取的包,第二是官方给出的一个ui界面。
这个界面可以自定义,默认是官方的,对于安全问题,以及ui路由设置需要着重思考。
自定义一个Docket的Bean
@Configuration @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.yss.ms.admin")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("接口列表 v1.1.0") // 任意,请稍微规范点 .description("接口测试") // 任意,请稍微规范点 .termsOfServiceUrl("http://localhost:8080/swagger-ui.html") // 将“url”换成自己的ip:port .contact("zsl") // 无所谓(这里是作者的别称) .version("1.1.0") .build(); } }
apiInfo中,主要配置一下Swagger2文档网站的信息,例如网站的title,网站的描述,联系人的信息,使用的协议等等。
在你要测试的controller的接口上加上Swagger2相关注解
@Api(description = "知识分类相关接口") @RestController public class KnowledgeSortsApi implements Apis { @Autowired private IKnowledgeSortsService knowledgeSortsService; @ApiOperation(value = "查询知识点分类", notes = "根据查询条件,分页查询知识点分类列表") @PostMapping(ADMIN_KNOWLEDGE_SORTS_PAGE_QUERY) public Resp<Page<KnowledgeSortsPageResult>> pageQueryList(@ApiParam(value = "分页查询条件", required = true) @RequestBody KnowledgeSortsPageDto knowledgeSortsPageDto) { Page<KnowledgeSortsPageResult> pageResult = knowledgeSortsService.pageQueryList(knowledgeSortsPageDto); return Resp.success(pageResult); } @ApiOperation(value = "知识点分类下一级树查询", notes = "根据父级id查询下一级分类树,默认查询所有分类") @ApiImplicitParam(name = "parentId", value = "知识点分类上级Id", required = false, paramType = "form", dataType = "long", defaultValue = "1") @GetMapping(API_KNOWLEDGE_SORTS_LIST) public Resp<KnowledgeSortListResult> getKnowledgeSortsList(@RequestParam(required = false, defaultValue = "1") Long parentId) { KnowledgeSortListResult knowledgeSortListResult = knowledgeSortsService.getKnowledgeSortsList(parentId); return Resp.success(knowledgeSortListResult); } }
public class KnowledgeSortTreeResult implements Serializable{ @ApiModelProperty(value = "知识点分类Id",required = true) private Long id; @ApiModelProperty(value = "知识点分类状态", required = true) private int knowledgeSortsStatus; @ApiModelProperty(value = "知识点分类名称", required = true) private String knowledgeSortsName; @ApiModelProperty(value = "知识点分类排序", required = true) private Integer knowledgeSortsSort; @ApiModelProperty(value = "知识点分类下一级树", required = true) private List<KnowledgeSortTreeResult> children = Lists.newArrayList(); }
public class KnowledgeSortsPageDto extends Pageable implements Serializable { @Comment("分类id") @ApiModelProperty(value = "知识点分类Id", required = false, example = "2") private Long knowledgeSortsId; @Comment("分类编码") @ApiModelProperty(value = "知识点分类编码", required = false, example = "") private String knowledgeSortsCode; @Comment("分类名称") @ApiModelProperty(value = "知识点分类名称", required = false, example = "") private String knowledgeSortsName; @ApiModelProperty(value = "知识点分类状态", required = false, example = "1") @Comment("分类状态") private Integer knowledgeSortsStatus; }
public class KnowledgeSortsPageResult implements Serializable{ @ApiModelProperty(name = "id", value = "知识点分类Id", required = true) private long id; @ApiModelProperty(value = "知识点分类编码", required = true) private String knowledgeSortsCode; @ApiModelProperty(value = "知识点分类名称", required = true) private String knowledgeSortsName; @ApiModelProperty(value = "知识点分类注释", required = true) private String knowledgeSortsRemark; @ApiModelProperty(value = "知识点分类排序", required = true) private int knowledgeSortsSort; @ApiModelProperty(value = "知识点分类状态", required = true) private int knowledgeSortsStatus; }
1.@Api(): 用于类,表示标识这个类是swagger的资源
tags–表示说明
value–也是说明,可以使用tags替代
2. @ApiOperation(): 用于方法,表示一个http请求的操作
value用于方法描述
notes用于提示内容
tags可以重新分组
3. @ApiImplicitParam(): 用于方法,表示单独的请求参数
4. @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
name–参数名称
value–参数说明
dataType–数据类型
paramType–参数类型 – query:请求类型为Json , form :请求为表单类型
example–举例说明
required-是否必须
5. @ApiModelProperty()用于方法,字段; 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明 (2.2.2版本bug造成example不显示,升级到2.4.0以上即可)
hidden–隐藏
@Api注解可以用来标记当前Controller的功能。
@ApiOperation注解
7ff7
用来标记一个方法的作用。
@ApiImplicitParam注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入。
• 如果有多个参数,则需要使用多个@ApiImplicitParam注解来描述,多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
• 需要注意的是,@ApiImplicitParam注解中虽然可以指定参数是必填的,但是却不能代替@RequestParam(required = true),前者的必填只是在Swagger2框架内必填,抛弃了Swagger2,这个限制就没用了,所以假如开发者需要指定一个参数必填,@RequestParam(required = true)注解还是不能省略
- SpringBoot和Swagger2整合的小demo
- SpringBoot整合Swagger2,再也不用维护接口文档了!
- SpringBoot(七):SpringBoot整合Swagger2
- 07 Spring Boot整合 Swagger2
- springBoot 整合 swagger2 构建RESTful API文档
- springboot整合Swagger2
- SpringBoot整合Swagger2,再也不用维护接口文档了!
- springboot 2 整合swagger2 以及遇到的一些坑
- Swagger(一) SpringBoot整合Swagger2简单的例子
- Spring Boot 整合mybatis 与 swagger2
- 简化说明:springboot整合swagger2
- SpringBoot2.0 整合 Swagger2 ,构建接口管理界面
- spring boot 整合 swagger2,并设置post,get请求方式
- SpringBoot(七):SpringBoot整合Swagger2
- Spring boot 整合 swagger2
- SpringBoot整合Swagger2案例,以及报错:java.lang.NumberFormatException: For input string: ""原因和解决办法
- spring boot 整合swagger2 实现动态生成接口文档
- Swagger(一) SpringBoot整合Swagger2简单的例子
- SpringBoot(七):SpringBoot整合Swagger2