SpringBoot整合Swagger2-笔记

1. 添加依赖

• Gradle

  implementation "io.springfox:springfox-swagger2:2.9.2"
  implementation "io.springfox:springfox-swagger-ui:2.9.2"
  

2. 添加配置

package com.ml.blog.system.config

import io.swagger.annotations.ApiOperation
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import springfox.documentation.builders.ApiInfoBuilder
import springfox.documentation.builders.ParameterBuilder
import springfox.documentation.builders.PathSelectors
import springfox.documentation.builders.RequestHandlerSelectors
import springfox.documentation.schema.ModelRef
import springfox.documentation.service.ApiInfo
import springfox.documentation.service.Contact
import springfox.documentation.service.Parameter
import springfox.documentation.spi.DocumentationType
import springfox.documentation.spring.web.plugins.Docket
import springfox.documentation.swagger2.annotations.EnableSwagger2

/**
 * swagger 配置
 *
 * @author 谭良忠
 * @date 2019/8/16 9:37
 */
@Configuration
@EnableSwagger2
class SwaggerConfig {

    @Bean
    fun createRestApi(): Docket {
        // 全局参数配置
        val params = mutableListOf<Parameter>()
        val param = ParameterBuilder().name("token").modelRef(ModelRef("string")).parameterType("header").required(false)
        params.add(param.build())

        return Docket(DocumentationType.SWAGGER_2)
                .globalOperationParameters(params) // 全局参数配置
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation::class.java))
                .paths(PathSelectors.any())
                .build()
    }

    private fun apiInfo(): ApiInfo {
        return ApiInfoBuilder()
                .title("Swagger API")
                .contact(Contact("LiangZhong.Tan", "", "liangzhong.tan@outlook.com"))
                .version("0.0.1")
                .build()
    }
}

访问 http://localhost:8080/swagger-ui.html

4. 常用注解说明

@Api 接口资源
@ApiOperation 描述针对特定路径的操作或通常为HTTP方法
@ApiParam 为操作参数添加其他元数据
@ApiModel 提供有关Swagger模型的其他信息。
@ApiModelProperty 添加和操作模型属性的数据

5. 代码栗子

• Controller

  import com.ml.blog.common.annotations.Permission
  import com.ml.blog.common.model.system.bo.MenuBo
  import com.ml.blog.common.model.vo.RestVo
  import com.ml.blog.system.service.MenuService
  import io.swagger.annotations.Api
  import io.swagger.annotations.ApiOperation
  import io.swagger.annotations.ApiParam
  import org.springframework.beans.factory.annotation.Autowired
  import org.springframework.web.bind.annotation.*
  
  /**
   * 菜单 - Controller
   * @author 谭良忠
   * @date 2019/11/8 9:10
   */
  @Api(tags = ["菜单控制器"])
  @RestController
  @RequestMapping("menu")
  class MenuController : BaseController() {
  
      @Autowired
      lateinit var menuService: MenuService
  
      @GetMapping("find/{id}")
      @ApiOperation("按主键查询")
      fun findById(@ApiParam(value = "菜单Id", required = true, example = "1") @PathVariable id: Long) = RestVo.success(menuService.findById(id))
  
      @Permission
      @GetMapping("tree")
      @ApiOperation("获取树型菜单")
      fun getTree() = RestVo.success(menuService.getTree(null))
  
      @Permission
      @GetMapping("user")
      @ApiOperation("获取用户菜单")
      fun getUserMenuTree() = RestVo.success(menuService.getTree(userId()))
  
      @Permission
      @PostMapping("save")
      @ApiOperation("保存菜单信息(menuId == null ? insert : update)")
      fun save(@ApiParam(value = "菜单信息", required = true) @RequestBody bo: MenuBo): RestVo<Any> {
          if (bo.menuId == null) {
              bo.creator = this.userId()
          }
          bo.updater = this.userId()
          return RestVo.success(menuService.save(bo))
      }
  
      @DeleteMapping("delete")
      @ApiOperation("按主键删除")
      fun deleteById(@ApiParam(value = "菜单Ids", required = true, example = "[1,2,3]") @RequestBody ids: List<Long>) = RestVo.success(menuService.deleteByIds(ids))
  }
  

• Entity

  import io.swagger.annotations.ApiModel
  import io.swagger.annotations.ApiModelProperty
  import java.util.*
  
  /**
   * 菜单 - Bo
   *
   * @author liangzhong
   * @date 2019/9/19 21:50
   */
  @ApiModel("菜单-Bo")
  class MenuBo {
  
      @ApiModelProperty("菜单Id")
      var menuId: Long? = null
  
      @ApiModelProperty("父级主键(顶级为0)")
      var parentId: Long? = null
  
      @ApiModelProperty("名称")
      var name: String? = null
  
      @ApiModelProperty("链接")
      var href: String? = null
  }
  

5. 相关问题

继承WebMvcConfigurationSupport后无法访问swagger解决方案 blog.csdn.net/liu0bing/ar…