使用springfox、swagger2生成api文档（也可使用https://github.com/apiaryio/api-blueprint 加 aglio） swagger全局参数头

0 SwaggerConfig.java

import java.util.List;

import org.springframework.context.annotation.Bean;

import com.google.common.collect.Lists;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
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;


/**
 * @author YANGLiiN
 * @date 2016-12-01 12:24
 */

@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket rmsApi() {
        List<Parameter> gps = Lists.newArrayList();
        Parameter p = new ParameterBuilder().name("sgs-username").description("员工工号（CAS登录后网关会传过来，前端无需关心）")
                .parameterType("header").modelRef(new ModelRef("string")).defaultValue("01368706").required(true)
                .build();
        gps.add(p);

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).globalOperationParameters(gps);
    }

    private ApiInfo apiInfo() {

        ApiInfo i = new ApiInfoBuilder().title("有信RMS系统API文档")
                                        .description("此文档为通讯组同学提供开发参考")
                                        // .license("有信 平台研发部")
                                        // .licenseUrl("http://www.uxin.com")
                                        .contact(new Contact("平台研发部-有信业务", "", "[email protected]"))

                                        .build();
        return i;
    }

}

LoginHandlerInterceptorAdapter.java

import javax.annotation.Resource;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.apache.commons.lang3.StringUtils;
import org.springframework.web.servlet.handler.HandlerInterceptorAdapter;

import com.xx.SysUserInfoManager;

import lombok.extern.slf4j.Slf4j;


@Slf4j
public class LoginHandlerInterceptorAdapter extends HandlerInterceptorAdapter {

    @Resource
    private SysUserInfoManager sysUserInfoManager;

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)
            throws Exception {

        String username = request.getHeader("sgs-username");
        if (StringUtils.isBlank(username)) {
            log.info("未登录访问{} {}", request.getMethod(), request.getRequestURI());

            response.setStatus(401);
            return false;
        } else {

            // 前端拉用户信息的时候自己判断

            // SysUserInfo user = sysUserInfoManager.selectUserByUserName(username);
            // if (user == null || user.getDelStatus()) {
            // log.info("已登录用户{}但没有访问统一事件平台管理后台权限访问{} {}", username, request.getMethod(), request.getRequestURI());
            //
            // response.setStatus(401);
            // return false;
            // }

            log.info("用户{}已登录", username);

            return true;
        }
    }
}

pom.xml

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>${jackson.version}</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-annotations</artifactId>
            <version>${jackson.version}</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>${jackson.version}</version>
        </dependency>

spring-mvc.xml

    <!-- Enables swgger ui-->
    <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
    <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

    <!-- Include a swagger configuration-->
    <bean name="applicationSwaggerConfig" class="com.uxin.feerate.conf.SwaggerConfig"/>






    <!--<mvc:cors>-->
    <!--<mvc:mapping path="/**" allowed-methods="GET,POST"/>-->
    <!--</mvc:cors>-->

    <mvc:interceptors>
        <mvc:interceptor>
            <mvc:mapping path="/**"/>
            <!--排除 swagger-->
            <mvc:exclude-mapping path="/swagger-ui.html"/>
            <mvc:exclude-mapping path="/swagger-resources/**"/>
            <mvc:exclude-mapping path="/webjars/**"/>
            <mvc:exclude-mapping path="/v2/api-docs/**"/>

            <bean class="com.sf.edp.admin.web.web.LoginHandlerInterceptorAdapter"/>
        </mvc:interceptor>
    </mvc:interceptors>

最后

在要加api说明的方法上添加    
@ApiOperation(value = "是否能拨打电话")

@ApiParam

@ApiResponse
等注解，详见：https://springfox.github.io/springfox/docs/current