Swagger

1 介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务()。 它的主要作用是：

1. 使得前后端分离开发更加方便，有利于团队协作

2. 接口的文档在线自动生成，降低后端开发人员编写接口文档的负担

3. 功能测试

Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，即可非常简单快捷的使用Swagger。

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!

目前，一般都使用knife4j框架。

2 使用步骤

1. 导入 knife4j 的maven坐标

在pom.xml中添加依赖

```xml

com.github.xiaoymin

knife4j-spring-boot-starter

3.0.2

```

2. 在配置类中加入 knife4j 相关配置

SwaggerConfig .java

```java

@Configuration

@Slf4j

public class SwaggerConfig extends WebMvcConfigurationSupport {

/**

* 通过knife4j生成接口文档

* @return

*/

@Bean

public Docket docket() {

ApiInfo apiInfo = new ApiInfoBuilder()

.title("智慧社区项目接口文档")

.version("1.0")

.description("智慧社区项目接口文档")

.build();

Docket docket = new Docket(DocumentationType.SWAGGER_2)

.groupName("管理端")

.apiInfo(apiInfo)

.select()

.apis(RequestHandlerSelectors.basePackage("com.bs.bszhsq.controller"))

.paths(PathSelectors.any())

.build();

return docket;

}

/**

* 设置静态资源映射

* @param registry

*/

@Override

protected void addResourceHandlers(ResourceHandlerRegistry registry) {

registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");

registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

}

}

```

3. 设置静态资源映射，否则接口文档页面无法访问

SwaggerConfig .java

```java

/**

* 设置静态资源映射

* @param registry

*/

protected void addResourceHandlers(ResourceHandlerRegistry registry) {

registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");

registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

}

```

4. 访问测试

接口文档访问路径为 http://==ip:port==/doc.html ---> 例子：http://localhost:8080/doc.html

3 常用注解

通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，常用注解如下：

| **注解** | **说明** |

| ----------------- | ------------------------------------------------------ |

| @Api | 用在类上，例如Controller，表示对类的说明 |

| @ApiModel | 用在类上，例如entity、DTO、VO |

| @ApiModelProperty | 用在属性上，描述属性信息 |

| @ApiOperation | 用在方法上，例如Controller的方法，说明方法的用途、作用 |

**后记

美好的一天，到此结束，下次继续努力！欲知后续，请看下回分解，写作不易，感谢大家的支持！！ **