我们要做的项目是一套接口,我们使用 Swagger 框架。

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。

 作用:

    1. 接口的文档在线自动生成。

    2. 功能测试。

 Swagger是一组开源项目,其中主要要项目如下:

1.   Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。

2.   Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。

3.   Swagger-js: 用于JavaScript的Swagger实现。

4.   Swagger-node-express: Swagger模块,用于node.js的Express web应用框架。

5.   Swagger-ui:一个无依赖的HTML、JS和CSS集合,可以为Swagger兼容API动态生成优雅文档。

6.   Swagger-codegen:一个模板驱动引擎,通过分析用户Swagger资源声明以各种语言生成客户端代码。

很简单的,在pom.xml中引入以下依赖

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

swagger 中有很多注解,可以大大简化代码量,提高开发效率。

例如:我们做一个查询数据库,并将结果返回的API

数据库的配置在 application.yml 文件中进行配置

控制层中:

@GetMapping(value = "common/getAreaByCityId") @ApiOperation(value = "根据城市ID获取区域") public ApiRes<List<AreaDto>> getAreaByCityId(int cityId) { List<AreaDto> data = commonService.getAreaByCityId(cityId); if (data != null) { return ApiRes.suc(data);

} else { return ApiRes.fail(); } }

@ApiOperation 注解的内容可以在 SwaggerUI 上展示出来

其中,AreaDto 类代码如下

@Data
@Accessors(chain = true)

public class AreaDto { @ApiModelProperty(value = "地区ID") private int id; @ApiModelProperty(value = "地区名称") private String name; @ApiModelProperty(value = "地区编码") private String areaCode; }

@Data 注解和 @Accessors 注解都来自lombok。他可以大大减少代码量,具体生产的Class代码就包含了 get、set、equals、toString 等方法。可以到IDEA 的 target/classes 中查看。

经过服务接口层 commonService ,具体实现在 实现层 commonServiceImpl

/**
 * 根据城市ID获取区域
 *
 * @param cityId
 * @return
 */
@Override
public List<AreaDto> getAreaByCityId(int cityId) {
    List<CityArea> cityAreas = cityAreaMapper.selectList(
            new QueryWrapper<CityArea>().lambda()
                    .eq(CityArea::getCityId, cityId)
                    .eq(CityArea::getState, CityAreaEnum.正常.getValue())
    );
    if (cityAreas.size() == 0) return null;
    
    List<AreaDto> data = new ArrayList<>();
    for (CityArea item : cityAreas) {
        data.add(new AreaDto()
                .setId(item.getId())
                .setName(item.getName())
                .setAreaCode(item.getAreaCode())
        );
    }
    return data;
}

这部分的代码意思是从 cityArea 数据库中查询数据,然后返回。

cityAreaMapper.selectList() 返回一个 List。

查询条件是 QueryWrapper 封装的 lambda 方式查询。详情请见 MyBatis-Plus

接下来遍历数组,将数据放入到 List<AreaDto> 中,并返回数据。

打开 localhost:8080/swagger-ui.html 就可以看到生成的接口了。


预期的返回数据格式:


swagger也可以直接测试接口:


Request URL 请求相应了我们预期的数据,一个接口就做好了!