Spring boot+swagger2构建restful api文档

这篇文章，我们简单介绍一下spring boot整合swagger2构建restful api文档。
什么是swagger
我们在开发一些restful风格的api时，通常会为调用者提供一套restful api说明文档。当我们的接口有调整时，就需要去更新api文档。而swagger是这样的一个框架，可以在开发接口的过程中通过注解的方式来描述我们开发的接口，从而保证restful api文档和接口代码的实时同步性。
Spring boot整合swagger2
1引入依赖
在pom.xml文件中引入swagger2依赖

<!-- 添加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>

2编写swagger2配置类
Swagger2.java

package com.yuxiaolong;

import org.springframework.beans.factory.annotation.Value;
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 yuxl
 * swagger配置类
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
   @Value("${swagger.show}")
   private boolean swaggerShow;


   @Bean
   public Docket createRestApi() {
      return new Docket(DocumentationType.SWAGGER_2)
            .enable(swaggerShow)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.yuxiaolong.controller"))
            .paths(PathSelectors.any())
            .build();
   }
   private ApiInfo apiInfo() {
      return new ApiInfoBuilder()
            .title("MY Site Swagger Restful API")
            .description("主要罗列了应用提供的api接口")
            .termsOfServiceUrl("https://www.wowjia.top/wojia/")
            .contact("yuxioalong")
            .version("1.0")
            .build();
   }
}

3在工程中的restful api中通过注解描述api

package com.yuxiaolong.controller;

import com.yuxiaolong.model.ModuleDO;
import com.yuxiaolong.service.ModuleService;
import com.yuxiaolong.utils.ApiResponse;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

/**
 * @author yuxl
 */
@RestController
@RequestMapping("/module")
public class ModuleController {
   @Autowired
   ModuleService moduleService;

   @ApiOperation("新增模块")
   @PostMapping("/add")
   @ResponseBody
   public ApiResponse addModule(@RequestBody
                            @ApiParam(name = "moduleDO", value = "模块实体类", required = true)
                                  ModuleDO moduleDO){
      moduleService.addModule(moduleDO);
      return  ApiResponse.success();
   }

   @ApiOperation("删除模块")
   @DeleteMapping("/delete/{id}")
   @ResponseBody
   public ApiResponse deleteModule(@ApiParam(name = "id", value = "模块id", required = true)
                              @PathVariable
                                    Integer id){
      moduleService.deleteModule(id);
      return ApiResponse.success();
   }

   @ApiOperation("更新模块")
   @PutMapping("/update")
   @ResponseBody
   public ApiResponse updateModule(@RequestBody
                              @ApiParam(name = "moduleDO", value = "模块实体类", required = true)
                                    ModuleDO moduleDO){
      moduleService.updateModule(moduleDO);
      return ApiResponse.success();
   }

   @ApiOperation("查询所有模块")
   @GetMapping("/list")
   @ResponseBody
   public List<ModuleDO> getModuleListByCondition(
                                          @ApiParam(name = "moduleName", value = "模块名称", required = false)
                                                String moduleName){
      return moduleService.getModuleListByCondition(null);
   }
}

4启动spring boot应用，访问restful api
启动应用，访问http://localhost:8080/swagger-ui.html

通过该ui页面，我们还可以调用接口进行调试

感谢大家百忙之中抽出宝贵的时间阅读本文，欢迎大家批评指正。微信扫下面二维码添加公众号议码评川，可获取java web、大数据、人工智能等相关学习资料。