Swagger
介绍
使用Swagger你只需要按照它的规范去定义接口及接口相关的信息,再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,以及在线接口调试页面等等。
官网:https://swagger.io/
knife4j 是为Java MVC框架集成Swagger生成Api文档的增强解决方案。
使用
-
导入knife4j的maven坐标
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>3.0.3</version> </dependency>
-
导入knife4j相关配置类
@Configuration @EnableKnife4j @EnableSwagger2 public class Knife4jConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.itoah.xxx.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("xx系统") .version("1.0") .description("xx系统接口文档") .build(); } }
-
设置静态资源,否则接口文档页面无法访问(如果你配置了拦截器),那么你需要将这些路径加入白名单
registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/favicon.ico").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
-
在LoginCheckFilter中设置不需要处理的请求路径(如果你配置了登录验证)但想在不登陆时也能访问,那么你需要将下面这些路径加入白名单
"/swagger-resources", "/v2/api-docs", "/webjars/**", "/doc.html"
常用注解
注解 | 说明 |
---|---|
@Api | 用在请求的类上,例如Controller,表示对类的说明 |
@ApiModel | 用在类上,通常是实体类,表示一个返回响应数据的信息 |
@ApiModelProperty | 用在属性上,描述响应类的属性 |
@ApiOperation | 用在请求方法上,说明方法的用途,作用 |
@ApilmplicitParams | 用在请求方法上,表示一组参数说明 |
@ApilmplicitParam | 用在@ApilmplicitParams注解中,指定一个请求参数的各个方面 |
例: