Swagger作用:
自动生成javaAPI,避免开发过程中接口文档更新不及时。
Swagger 一.导入依赖:
导入依赖
<!--swagger包--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.2.2</version> </dependency> <!--swagger包结束-->
|
Swagger 二.Swagger首页的配置:
创建一个SwaggerConfig类,通过@Configuration托管给spring,然后通过@EnableSwagger2 注解开启Swagger,Config类大部分都是固定的,没什么改变的需要:
代码:
package com.zy100.config;
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;
/** * @author 赵振宇 * @date 2019/10/29 0029 * @time 14:51 * @desc Swagger配置类,该类里面的应该是固定的,主要用来设置文档的主题信息,比如文档的大标题,副标题,公司名 * 等 */ @Configuration//托管spring @EnableSwagger2//开启swagger功能 public class SwaggerConfig { /** * 创建API应用 * apiInfo() 增加API相关信息 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现, * 本例采用指定扫描的包路径来定义指定要建立API的目录。 * * @return */ @Bean public Docket createRestApi(){ //版本类型是swagger2 return new Docket(DocumentationType.SWAGGER_2) //通过调用自定义方法apiInfo,获得文档的主要信息 .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.zy100.controller"))//扫描该包下面的API注解 .paths(PathSelectors.any()) .build(); } /** * 创建该API的基本信息(这些基本信息会展现在文档页面中) * 访问地址:http://项目实际地址/swagger-ui.html * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("使用Swagger2 构建RESTful APIS - zy") //接口管理文档首页显示 .description("zy - Swagger使用演示")//API的描述 .termsOfServiceUrl("www.footmark.top")//网站url等 .version("1.0") .build(); } }
|
Swagger 三.Swagger的Controller示例
在需要生成接口文档的Controller中加上@API注解,类中需要生成接口的方法上加上@ApiOperation注解:
代码:
package com.zy100.controller;
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.*;
import java.util.Date; import java.util.HashMap; import java.util.Map;
/** * @author 赵振宇 * @date 2019/10/29 0029 * @time 15:00 * @desc 配合swagger创建一个Controller,演示方便不再创建service层 */ @RestController @Api("用户模块API文档")//注解api说明该类需要生成api文档 public class UserController { /** * 该类中 * @param map 类似于一个user对象 * key就是对象的属性 * value就是对象的属性值 * ------------------------ * 属性 id name birthday * @return * */ //正常业务整添加是对象,前台传JSON对象,在此使用map代替 @PostMapping("/user")//如果使用swagger自动生成接口文档,一定要加上请求类型,不然会导致swagger把所有请求都会生成一下 @ApiOperation("添加用户") @ApiImplicitParams({ @ApiImplicitParam(name = "map",//参数名字 value = "这是一个添加的对象",//参数的描述 required = true,//是否必须传参数,true是 paramType = "body")//参数类型 body代表json }) public Map add(@RequestBody Map map){ return map; } //根据id删除数据。 @DeleteMapping("/user/{id}") @ApiOperation("删除用户")//API中说明的该类的作用 @ApiImplicitParams({ @ApiImplicitParam(name = "id",//参数名字 value = "用户id",//参数的描述 required = true,//是否必须传参数,true是 paramType = "path",//参数类型 path代表路径参数 dataType = "int")//参数类型 int }) public String deltete(@PathVariable int id){ return "{code:200,msg:删除"+id+"成功}"; } //根据传入的对象信息进行更新 @PutMapping("/user") @ApiOperation("更新用户")//API中说明的该类的作用 @ApiImplicitParams({ @ApiImplicitParam(name = "map",//参数名字 value = "更新的用户",//参数的描述 required = true,//是否必须传参数,true是 paramType = "body",//参数类型 body dataType = "map")//参数类型 int }) public Map update(@RequestBody Map map){ return map; } @GetMapping("/user/{id}") @ApiOperation("查询永不用户")//API中说明的该类的作用 @ApiImplicitParams({ @ApiImplicitParam(name = "id",//参数名字 value = "查询的用户id",//参数的描述 required = true,//是否必须传参数,true是 paramType = "path",//参数类型 body dataType = "int")//参数类型 int }) public Map getOne(@PathVariable int id){ Map<String,Object> map = new HashMap<>(); map.put("id",id); map.put("name","张三"); map.put("birthday",new Date()); return map; } }
|
Swagger 四.测试
运行启动类主方法,访问:http://localhost:8080/swagger-ui.html
可以看到效果