Swagger的使用及注解说明

一、使用方法

在pom.xml中加入Swagger2的依赖

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

创建Swagger2配置类

在Application.java同级创建Swagger2的配置类Swagger2。

@Configuration @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("需要查看的包名或类名")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot中使用Swagger2构建RESTful APIs") .description("更多Spring Boot相关文章请关注：http://blog.didispace.com/") .termsOfServiceUrl("http://blog.didispace.com/") .contact("程序猿DD") .version("1.0") .build(); } }

通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。

再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

@Api(value = "user",  tags = "用户模块")
@RestController
@RequestMapping("user")
public class UserController extends BaseController {

    @Resource
    private UserService userService;

    @ApiOperation(value = "用户添加")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "user",value = "用户" ,required = true,dataType = "String", paramType="body")
    })
    @RequestMapping(value = "addUser",method = RequestMethod.POST)
    public ResultBean addUser(User user){
        return  resultBean;
    }
}

完成上述代码添加上，启动Spring Boot程序，访问：http://localhost:${port}/${context-path}/swagger-ui.html

 

二、解决404的问题

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

@Configuration
public class SwaggerConfiger extends WebMvcConfigurationSupport{

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry){
        // 解决静态资源无法访问
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

 

三、注解说明

作用范围	API	使用位置
对象属性	@ApiModelProperty	用于出入参数对象的字段上
协议集描述	@Api	用于Controller类上
协议描述	@ApiOperation	用在Controller的方法上
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses里边
非对象参数集	@ApiImplicitParams	用在controller的方法上
非对象参数描述	@ApiImplicitParam	用在@ApiImplicitParams的方法里边
描述返回对象的意义	@ApiModel	用在返回对象类上

关于参数的详细解释

属性	取值	作用
paramType		查询参数类型
	path	以地址的形式提交数据
	query	直接跟参数完成自动映射赋值
	body	以流的形式提交 仅支持POST
	header	参数在request headers 里边提交
	form	以form表单的形式提交 仅支持POST
dataType		参数的数据类型 只作为标志说明，并没有实际验证
	Long
	String
name		接收参数名（必须与方法中参数名一致）
value		接收参数的意义描述（描述信息）
required		参数是否必填
	true	必填
	false	非必填
defaultValue		默认值