SpringBoot整合Swagger接口文档

1、整合Swagger3接口文档

　　前后端分离的项目，接口文档的存在十分重要。与手动编写接口文档不同，swagger是一个自动生成接口文档的工具，在需求不断变更的环境下，手动编写文档的效率实在太低。与新版的swagger3相比swagger2配置更少，使用更加方便。

步骤一：引入Swagger3依赖

<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version></dependency>

步骤二：Application启动类上面加入@EnableOpenApi注解

@EnableOpenApi@SpringBootApplication@MapperScan(basePackages={"com.singerw.dao"})publicclassSingerwblogApplication{publicstaticvoidmain(String[]args){SpringApplication.run(SingerwblogApplication.class,args);}}

步骤三：配置Swagger3Config.java

@ConfigurationpublicclassSwagger3Config{@BeanpublicDocketcreateRestApi(){returnnewDocket(DocumentationType.OAS_30).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.etc.swagger.controller")).paths(PathSelectors.any()).build();}privateApiInfoapiInfo(){returnnewApiInfoBuilder().title("Swagger3接口文档").description("个人博客项目文档。").contact(newContact("ZhangSingerw。","http://www.singerw.com","zhangsingerw@gmail.com")).version("1.0").build();}}

步骤四：访问

Swagger的访问路径由http://127.0.0.1:8080/swagger-ui.html改成了http://127.0.0.1:8080/swagger-ui/ 或http://127.0.0.1:8080/swagger-ui/index.html

Swagger3自定义Ui

Swagger有很多可以自定义的ui，这里只举例以下两种：

<dependency><groupId>com.zyplayer</groupId><artifactId>swagger-mg-ui</artifactId><version>1.0.6</version></dependency>

导入包后访问：http://localhost:8080/document.html

<!--老版本引用--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.6</version></dependency><!--新版本引用--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-ui</artifactId><version>3.0.3</version></dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>${knife4j.version}</version></dependency>

导入包后访问：http://localhost:8080/doc.html

2、整合Swagger2接口文档

步骤一：导入依赖

<!--swagger2start--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.1</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency><dependency><groupId>org.webjars</groupId><artifactId>bootstrap</artifactId><version>3.3.5</version></dependency><!--swagger2end-->

步骤二：新建Swagger2Config配置类

@Configuration@EnableSwagger2publicclassSwagger2Config{//swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等@Bean创建一个beanpublicDocketcreateRestApi(){returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()//为当前包路径.apis(RequestHandlerSelectors.basePackage("com.singerw.controller")).paths(PathSelectors.any()).build();}//构建api文档的详细信息函数,注意这里的注解引用的是哪个privateApiInfoapiInfo(){returnnewApiInfoBuilder()//页面标题.title("SpringBoot测试使用Swagger2构建RESTfulAPI")//创建人.contact(newContact("小白","http://singerw.com",""))//版本号.version("1.0")//描述.description("API描述").build();}}

步骤三：访问

http://127.0.0.1:8080/swagger-ui.html

3、Swagger常用注解的使用说明

@Api：用在请求的类上，表示对类的说明tags="说明该类的作用，可以在UI界面上看到的注解"value="该参数没什么意义，在UI界面上也看到，所以不需要配置"@ApiOperation：用在请求的方法上，说明方法的用途、作用value="说明方法的用途、作用"notes="方法的备注说明"@ApiImplicitParams：用在请求的方法上，表示一组参数说明@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面name：参数名value：参数的汉字说明、解释required：参数是否必须传paramType：参数放在哪个地方·header-->请求参数的获取：@RequestHeader·query-->请求参数的获取：@RequestParam·path（用于restful接口）-->请求参数的获取：@PathVariable·body（不常用）·form（不常用）dataType：参数类型，默认String，其它值dataType="Integer"defaultValue：参数的默认值@ApiResponses：用在请求的方法上，表示一组响应@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息code：数字，例如400message：信息，例如"请求参数没填好"response：抛出异常的类@ApiModel：用于响应类上，表示一个返回响应数据的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）@ApiModelProperty：用在属性上，描述响应类的属性

4、Controller层的配置示例

@Api(tags="用户信息管理")@RestController@RequestMapping("userRecord")publicclassUserRecordControllerextendsApiController{/***服务对象*/@ResourceprivateUserRecordServiceuserRecordService;/***分页查询所有数据*@parampage分页对象*@paramuserRecord查询实体*@return所有数据*/@ApiOperation("分页查询所有数据")@GetMapping("page")publicRselectAll(Page<UserRecord>page,UserRecorduserRecord){returnsuccess(this.userRecordService.page(page,newQueryWrapper<>(userRecord)));}/***通过主键查询单条数据*@paramid主键*@return单条数据*/@ApiOperation("通过主键查询单条数据")@GetMapping("{id}")publicRselectOne(@PathVariableSerializableid){returnsuccess(this.userRecordService.getById(id));}/***新增数据*@paramuserRecord实体对象*@return新增结果*/@ApiOperation("新增数据")@PostMapping("insert")publicRinsert(@RequestBodyUserRecorduserRecord){returnsuccess(this.userRecordService.save(userRecord));}/***修改数据*@paramuserRecord实体对象*@return修改结果*/@ApiOperation("修改数据")@PutMapping("update")publicRupdate(@RequestBodyUserRecorduserRecord){returnsuccess(this.userRecordService.updateById(userRecord));}/***删除数据*@paramidList主键结合*@return删除结果*/@ApiOperation("删除数据")@DeleteMapping("delete")publicRdelete(@RequestParam("idList")List<Long>idList){returnsuccess(this.userRecordService.removeByIds(idList));}}