springmvc整合swagger2接口文檔

一、引入jar包，我使用版本的是2.7.0，版本自選

<!-- swagger2接口文檔 -->
		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger2</artifactId>
		</dependency>
		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger-ui</artifactId>
		</dependency>複製代碼

二、swagger2的配置文件，關於springmvc掃描的xml我就不貼了，至此基本配置好了

package com.shop.config;

import io.swagger.annotations.ApiOperation;

import java.util.ArrayList;
import java.util.List;
import java.util.Map.Entry;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import com.shop.common.result.RC;

/**
 * @author Mr.chen
 * @version 建立時間：2018年6月28日 上午10:42:01
 * @ClassName 類名稱
 * @Description 類描述
 */
@Configuration
@ComponentScan(basePackages = {"com.shop.modular.*.controller"})
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport{

    /**
     * 文檔生成
     * @return
     */
    @Bean
    public Docket ssoApi() {
    	return newDocket("com.shop.modular.sso.controller","登陸接口");
    }

    @Bean
    public Docket orderApi() {
    	return newDocket("com.shop.modular.order.controller","訂單接口");
    }

    
    /**
     * 建立文檔
     * @param basePackage 包全路徑  例com.shop.modular.example.controller
     * @param groupName   名字
     * @return
     */
    private Docket newDocket( String basePackage ,String groupName ){
    	List<ResponseMessage> responseMessages = getResponseMessage();
		 return new Docket(DocumentationType.SWAGGER_2).groupName(groupName)
	            .useDefaultResponseMessages(false)    //不使用默認返回
	            .globalResponseMessage(RequestMethod.GET, responseMessages)
	            .globalResponseMessage(RequestMethod.PUT, responseMessages)
	            .globalResponseMessage(RequestMethod.POST, responseMessages)
	            .globalResponseMessage(RequestMethod.DELETE, responseMessages)
	            .globalOperationParameters(getParameterList())   //設置公共參數
                    //文檔頭部信息，做者信息等等，自行填寫
	            .apiInfo(new ApiInfoBuilder()      
			                .title(groupName)
			                .description("返回數據格式統一爲 { code:返回碼 , msg:\"\" , data:{} 或 data:[] }")
			                .version("1.0")
			                .build())
	            .select()
	            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))   //掃描該註解的方法
	            .apis(RequestHandlerSelectors.basePackage(basePackage))  
	            .paths(PathSelectors.any())
	            .build();
    }
    
    /**
     * 設置公共請求參數
     * @return
     */
	private List<Parameter> getParameterList(){
		ParameterBuilder tokenPar = new ParameterBuilder();
		List<Parameter> pars = new ArrayList<Parameter>();
		tokenPar.name("x-access-token").description("令牌,須要登陸的操做必填").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
		pars.add(tokenPar.build());
		return pars;
	}
    
    /**
     * 設置返回信息
     * @return
     */
    private ArrayList<ResponseMessage> getResponseMessage(){
    	ArrayList<ResponseMessage> responseMessages=new ArrayList<>(); //配置公共返回
    	 responseMessages.add(new ResponseMessageBuilder().code(404).message("找不到路徑").responseModel(new ModelRef("Error")).build()); 
	return responseMessages;
    }
    
    
    /**
     * 配置靜態資源
     */
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
		registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
		registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
	}
    
    

    
}
複製代碼

三、controller代碼 用做文檔測試

package com.shop.modular.example.controller;


import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;

import java.util.List;

import javax.servlet.http.HttpServletRequest;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.shop.common.jedis.JedisClient;
import com.shop.common.result.R;
import com.shop.common.result.RC;
import com.shop.common.util.JsonUtils;
import com.shop.modular.example.entity.Testplus;
import com.shop.modular.example.mapper.TestplusMapper;
import com.shop.modular.example.service.ITestplusService;

/**
 * <p>
 *  前端控制器
 * </p>
 * 例子
 * @author chenzhenrong
 * @since 2018-06-28
 */
@Api(value="測試",tags={"測試"}) //標題
@RestController
@RequestMapping("/testplus")
public class TestplusController {
	
	@Autowired
	private ITestplusService service;
	
	@Autowired
	private JedisClient redis;
	
	@Autowired
	private TestplusMapper testplusMapper;
	
	/**
     * @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：數字，例如400
        message：信息，例如"請求參數沒填好"
        response：拋出異常的類

@ApiModel：用於響應類上，表示一個返回響應數據的信息
            （這種通常用在post建立的時候，使用@RequestBody這樣的場景，
            請求參數沒法使用@ApiImplicitParam註解進行描述的時候）
    @ApiModelProperty：用在屬性上，描述響應類的屬性
     * @return
     */
	@ApiOperation(value = "測試文本")//swagger 接口說明
	@ApiResponses(value = {@ApiResponse(500 ,message="人品問題"})
	@PostMapping(value="{id}")
	public R<List<Testplus>> test(HttpServletRequest request , @PathVariable int id , @RequestBody Testplus t){
		System.out.println("param = "+JsonUtils.objectToJson(t));
		System.out.println(JsonUtils.objectToJson(t.selectAll()));
		return R.ok(testplusMapper.selectAllData());
	}
	
	
}

複製代碼

四、實體類註解

package com.shop.modular.example.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.util.Date;

import com.baomidou.mybatisplus.activerecord.Model;
import com.baomidou.mybatisplus.annotations.TableId;
import com.baomidou.mybatisplus.annotations.TableName;
import com.baomidou.mybatisplus.annotations.Version;
import com.baomidou.mybatisplus.enums.IdType;

import java.io.Serializable;

/**
 * <p>
 * 
 * </p>
 *
 * @author chenzhenrong
 * @since 2018-06-28
 */
@ApiModel
public class Testplus extends Model<Testplus> {

    private static final long serialVersionUID = 1L;

    /**
     * ID
     */
    private String id;
    /**
     * 文本類
     */
    @ApiModelProperty(value="文本類")
    private String text;
    /**
     * 時間
     */
    private Date datetime;
    /**
     * 狀態
     */
    private Integer state;
    /**
     * 版本號
     */
    @Version
    private Integer version;


    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getText() {
        return text;
    }

    public void setText(String text) {
        this.text = text;
    }

    public Date getDatetime() {
        return datetime;
    }

    public void setDatetime(Date datetime) {
        this.datetime = datetime;
    }

    public Integer getState() {
        return state;
    }

    public void setState(Integer state) {
        this.state = state;
    }

    public Integer getVersion() {
        return version;
    }

    public void setVersion(Integer version) {
        this.version = version;
    }

    @Override
    protected Serializable pkVal() {
        return this.id;
    }

    @Override
    public String toString() {
        return "Testplus{" +
        ", id=" + id +
        ", text=" + text +
        ", datetime=" + datetime +
        ", state=" + state +
        ", version=" + version +
        "}";
    }
}
複製代碼

五、啓動項目後，打開IP端口+/swagger-ui.html 便可訪問

可能出現問題

一、頁面訪問404，留意你mvc.xml的配置與web.xml的配置是否對訪問路徑進行攔截等等。