SpringBoot之Swagger2文档生成

Posted 2020-11-30 贝贝

SpringBoot之Swagger2文档生成

1、Swagger2介绍

编写和维护接口文档是每个程序员的职责，前面我们已经写好的接口现在需要提供一份文档，这样才能方便调用者使用。考虑到编写接口文档是一个非常枯燥的工作，我们采用Swagger2这套自动化文档工具来生成文档，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。 

2、SpringBoot开启Swagger2支持

第一步：在pom.xml中加入Swagger2的依赖

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency>

 

第二步：创建Swagger2配置类

package com.offcn.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;   @Configuration @EnableSwagger2 public class SwaggerConfig {     public Docket createRestApi() {         return new Docket(DocumentationType.SWAGGER_2)                 .apiInfo(apiInfo())                 .select()                 .apis(RequestHandlerSelectors.basePackage("com.offcn.controller"))                 .paths(PathSelectors.any())                 .build();     }     private ApiInfo apiInfo() {         return new ApiInfoBuilder()                 .title("Spring Boot中使用Swagger2构建RESTful APIs")                 .description("优就业")                 .termsOfServiceUrl("http://www.ujiuye.com/")                 .contact("Sunny")                 .version("1.0")                 .build();     } }

 

3、修改Controller增加文档注释

通过@ApiOperation注解来给API增加说明 通过@ApiImplicitParams@ApiImplicitParam注解来给参数增加说明

/**  * 更新指定id用户信息  * @param id  * @param user  * @return  */ @PutMapping("/{id}") @ApiOperation(value="更新指定id用户信息", notes="根据id更新用户信息") @ApiImplicitParams({          @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),          @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")      }) public String updateUser(@PathVariable("id") Long id,User user) { user.setId(id); userRepository.saveAndFlush(user); return "success"; }   /***  * 删除指定id用户  * @param id  * @return  */ @DeleteMapping("/{id}") @ApiOperation(value="删除指定id用户信息", notes="根据id删除用户信息")     @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long") public String deleteUser(@PathVariable("id") Long id) {   userRepository.deleteById(id); return "success";   }

 

4、查看Swagger2文档

重启应用访问地址：http://localhost:8080/swagger-ui.html 

点开每个接口，可以查看接口详情