你的項目接口，還在自己手寫接口文檔嗎？

首先聲明一下，本篇不僅僅介紹的是集成swagger在線文檔，還集成了它的好搭檔knife4j，而且集成方法很簡單，效果圖如下：

  

怎麼樣，頁面也比你手寫的文檔好看吧。而且整個文檔，都是通過你的實體entity或者vo，以及controller接口直接返回，你不需要特意去寫很多代碼文檔，現在一點一點介紹：

一、先集成swagger

第一步：配置pom.xml

<dependency>

     <groupId>io.springfox</groupId>

     <artifactId>springfox-swagger2</artifactId>

     <version> 2.9 . 2 </version>

</dependency>

<dependency>

     <groupId>io.springfox</groupId>

     <artifactId>springfox-swagger-ui</artifactId>

     <version> 2.9 . 2 </version>

</dependency>

<dependency>

     <groupId>com.github.xiaoymin</groupId>

     <artifactId>knife4j-spring-boot-starter</artifactId>

     <version> 2.0 . 2 </version>

</dependency>

第二步：配置swagger和knife4j文件

具體如下：

package   com.web.config.api;

 

import   com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;

import   io.swagger.annotations.Api;

import   org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;

import   org.springframework.context.annotation.Bean;

import   org.springframework.context.annotation.Configuration;

import   org.springframework.context.annotation.Import;

import   springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;

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;

 

/**

  * swagger配置

  */

@Configuration

@EnableSwagger2

@EnableKnife4j

@Import (BeanValidatorPluginsConfiguration. class )

public   class   SwaggerConfig {

     @Bean (value =  "defaultApi2" )

     public   Docket defaultApi2() {

         Docket docket= new   Docket(DocumentationType.SWAGGER_2)

                 .apiInfo(apiInfo())

                 //分組名稱

                 .groupName( "1.X版本" )

                 .select()

                 //這裏指定Controller掃描包路徑(項目路徑也行)

                 .apis(RequestHandlerSelectors.basePackage( "com.web.controller" ))

                 .paths(PathSelectors.any())

                 .build();

         return   docket;

     }

 

     private   ApiInfo apiInfo() {

         return   new   ApiInfoBuilder()

                 .title( "xxxknife4j接口管理平臺" )

                 .description( "xxxknife4j接口管理平臺" )

                 .termsOfServiceUrl( "http://localhost:8080/" )

                 .contact( "[email protected]" )

                 .version( "1.0" )

                 .build();

     }

}

第三步：使用註解來進行啓動swagger

a.啓動類上面添加註解@EnableSwagger2，代表允許swagger文檔展現

b.啓動類實現WebMvcConfigurer接口：

@Override

public   void   addResourceHandlers(ResourceHandlerRegistry registry) {

     System.out.println( "這裏是addResourceHandlers方法" );

     registry.addResourceHandler( "doc.html" ).addResourceLocations( "classpath:/META-INF/resources/" );

     registry.addResourceHandler( "/webjars/**" ).addResourceLocations( "classpath:/META-INF/resources/webjars/" );

}

第四步：配置Controller

package   com.web.controller.sys;

 

import   com.web.common.Result;

import   com.web.controller.base.BaseController;

import   com.web.dto.sys.SysUserParamDTO;

import   com.web.entity.sys.SysUser;

import   com.web.entity.sys.SysVillage;

import   com.web.service.sys.SysUserService;

import   com.web.service.sys.SysVillageService;

import   com.web.utils.JsonUtil;

import   io.swagger.annotations.Api;

import   io.swagger.annotations.ApiOperation;

import   lombok.extern.slf4j.Slf4j;

import   org.springframework.beans.factory.annotation.Autowired;

import   org.springframework.web.bind.annotation.*;

 

import   java.util.List;

 

/**

  * 小區模塊

  */

@RestController

@RequestMapping ( "/sysVillage" )

@Slf4j

@Api (value =  "/sysVillage" ,tags =  "小區模塊" )

public   class   SysVillageController  extends   BaseController {

 

     @Autowired

     private   SysVillageService sysVillageService;

 

     /**

      * 小區列表

      * @return

      */

     @ApiOperation (value =  "小區列表" ,notes =  "小區列表" ,hidden =  false )

     @PostMapping ( "/w_list" )

     public   Result<List<SysVillage>> listPage( @RequestParam (name =  "name" ) String name){

         log.info( "進入了小區列表接口，傳遞的參數：" + name);

         SysVillage sysVillageSearch =  new   SysVillage();

         sysVillageSearch.setName(name);

         List<SysVillage> list = sysVillageService.findAll(sysVillageSearch);

         for (SysVillage sysVillage:list){

             sysVillage.setExt_location( "廣東省廣州市黃埔區" );

         }

         return   Result.succResult(list);

     }

}

上面@Api代表該文檔菜單名稱，也就是模塊名稱

@ApiOperation代表接口名稱

然後具體就需要你去了解swagger參數編寫說明了，這裏不詳解。

swagger會根據你的返回對象進行文檔話，比如上面我的是返回SysVillage集合對象，可以看看我的對象內容：

package   com.web.entity.sys;

 

import   com.web.entity.base.BaseEntity;

import   io.swagger.annotations.ApiModelProperty;

import   lombok.Data;

 

@Data

public   class   SysVillage  extends   BaseEntity {

     @ApiModelProperty (value= "區/縣code" )

     private   String countycode;

 

     @ApiModelProperty (value= "小區名稱" )

     private   String name;

 

     @ApiModelProperty (value= "小區描述" )

     private   String remark;

 

     @ApiModelProperty (value= "小區經度" )

     private   String longitude;

 

     @ApiModelProperty (value= "小區緯度" )

     private   String latitude;

 

     @ApiModelProperty (value= "小區圖片" )

     private   String picurl;

 

     @ApiModelProperty (value= "是否激活(0:否,1:是)" )

     private   Integer status;

 

     //擴展字段

     @ApiModelProperty (value= "詳細地址" )

     private   String ext_location;

}

@ApiModelProperty代表字段參數說明

第五步：訪問knife4j文檔：

http://localhost:8080/doc.htm