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的配置是否对访问路径进行拦截等等。