SpringBoot整合Swagger接口文档
发布网友
发布时间：2024-09-26 06:32
共1个回答
热心网友
时间：2024-10-10 12:10
前后端分离的项目，接口文档的存在十分重要。与手动编写接口文档不同，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."})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自定义UiSwagger有很多可以自定义的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,UserRecorserRecord){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(@RequestBodyUserRecorserRecord){returnsuccess(this.userRecordService.save(userRecord));}/***修改数据*@paramuserRecord实体对象*@return修改结果*/@ApiOperation("修改数据")@PutMapping("update")publicRupdate(@RequestBodyUserRecorserRecord){returnsuccess(this.userRecordService.updateById(userRecord));}/***删除数据*@paramidList主键结合*@return删除结果*/@ApiOperation("删除数据")@DeleteMapping("delete")publicRdelete(@RequestParam("idList")List<Long>idList){returnsuccess(this.userRecordService.removeByIds(idList));}}