配置

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.6.1</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.6.1</version>
		</dependency>

注意, 是没有 @Configuration . 加了的话可能会报以下错误

NoSuchBeanDefinitionException: No qualifying bean of type [java.util.List] found for dependency [java.util.List<org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping>

@EnableSwagger2
@Configuration
@EnableWebMvc
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

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

访问 http://host:port/web-app-name/swagger-ui.html

在非 spring boot 环境下配置

doc

使用

类级别

@Api 一般用来描述某一类 api. 例子:

/**
 * 广告组相关接口
 */
@Controller
@RequestMapping("/adgroup")
@Api(value = "广告组相关的 api", tags = {"adGroup", "广告组"})
public class AdGroupController {
}

方法级别

某个具体的 URL 的完整描述

@ApiOperation

描述该方法是干什么的.

@ApiOperation(value = "添加广告组")

@ApiImplicitParams 或 @ApiImplicitParam

描述该方法中, 各个参数(多个参数时, 使用 @ApiImplicitParams, 单个参数时, 可以简化为 @ApiImplicitParam)

例如

    @ApiImplicitParams({
            @ApiImplicitParam(name = "groupName", value = "广告组名", required = true, paramType = ParameterTools.FORM, dataTypeClass = String.class),
            @ApiImplicitParam(name = "memo", value = "备注", paramType = ParameterTools.FORM, dataTypeClass = String.class),
            @ApiImplicitParam(name = "platform", value = "所属平台." + AllowableValuesTools.PLATFORMS_DES, paramType = ParameterTools.FORM, dataType = "int", defaultValue = "1", allowableValues = AllowableValuesTools.PLATFORMS),
    })

paraType : 为参数类型, 看文档可知它允许的值为: (我写了个常量类, 方便使用)

    public static final String FORM = "form";
    public static final String QUERY = "query";
    public static final String PATH = "path";
    public static final String BODY = "body";
    public static final String HEADER = "header";

默认情况下, 它会自动与Spring中的注解对应:

header 对应注解：@RequestHeader
query 对应注解：@RequestParam
path 对应注解: @PathVariable
body 对应注解: @RequestBody

dataType 或 dataTypeClass : 表示参数的数据类型

defaultValue 表示参数的默认值

allowableValues 表示参数的允许值(用逗号分隔)

注意

最好在 Controller 中, 指定接收或返回的对象, 而不要笼统Object 或 Map<> 之类的 抽象 类. 不然没法使用 @ApiModel 之类的注解.