XMall项目集成Swagger2实现API文档自动化指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00320/article/details/148464510

XMall项目集成Swagger2实现API文档自动化指南

xmall 基于SOA架构的分布式电商购物商城前后端分离前台商城:Vue全家桶后台管理系统:Dubbo/SSM/Elasticsearch/Redis/MySQL/ActiveMQ/Shiro/Zookeeper等项目地址: https://gitcode.com/gh_mirrors/xm/xmall

一、Swagger2简介

Swagger2是一个开源的API文档工具，它能够自动生成、描述、调用和可视化RESTful风格的Web服务。在XMall项目中集成Swagger2可以带来以下优势：

自动生成API文档，减少手动编写的工作量
提供交互式API测试界面
保持文档与代码同步更新
支持多种语言和框架

二、XMall集成Swagger2详细步骤

1. 添加Maven依赖

首先需要在项目的pom.xml文件中添加Swagger2相关依赖：

<!-- swagger2核心依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>
<!-- swagger2 UI界面依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>

2. 配置Swagger2

在XMall项目中，创建Swagger2配置类Swagger2Config：

@Configuration
@EnableWebMvc
@EnableSwagger2
public class Swagger2Config {
    
    private static final Logger log = LoggerFactory.getLogger(Swagger2Config.class);
    
    @Bean
    public Docket createRestApi() {
        log.info("初始化Swagger2配置");
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 使用注解方式扫描API
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XMall商城API文档")
                .description("XMall商城前后端交互API接口文档")
                .version("1.0.0")
                .contact(new Contact("开发团队", "http://blog.exrick.cn", "1012139570@qq.com"))
                .build();
    }
}

3. 编写API接口文档

在Controller中使用Swagger注解来描述API：

@RestController
@Api(tags = "会员管理", description = "会员相关操作接口")
public class MemberController {

    @Autowired
    private MemberService memberService;

    @GetMapping("/member/list")
    @ResponseBody
    @ApiOperation(value = "获取会员列表", notes = "分页查询会员信息")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "draw", value = "请求次数计数器", required = true),
        @ApiImplicitParam(name = "start", value = "起始位置", required = true),
        @ApiImplicitParam(name = "length", value = "每页条数", required = true),
        @ApiImplicitParam(name = "search", value = "搜索条件", required = false)
    })
    public DataTablesResult getMemberList(int draw, int start, int length, 
                                         @RequestParam("search[value]") String search) {
        return memberService.getMemberList(draw, start, length, search);
    }
}

4. 解决404问题

在XMall项目中，如果直接访问/swagger-ui.html出现404，可以按照以下步骤解决：

下载Swagger UI静态资源文件
将dist目录下的所有文件复制到项目的static/swagger目录
修改index.html中的API文档地址：

// 修改前
// url = "http://petstore.swagger.io/v2/swagger.json";        
// 修改后
url = "http://localhost:8888/v2/api-docs";

通过http://localhost:8888/static/swagger/index.html访问

三、Swagger2高级用法

1. 响应结果描述

@ApiOperation(value = "获取图片资源", response = byte[].class)
@ApiResponses({
    @ApiResponse(code = 200, message = "成功获取图片"),
    @ApiResponse(code = 404, message = "图片不存在")
})
@GetMapping(value = "/files/images/{id}", produces = "image/jpeg;image/png;image/gif")
public ResponseEntity<String> getImg(@PathVariable("id") long id) {
    return new ResponseEntity<>(fileService.getFileBydId(id), HttpStatus.OK);
}

2. 常用注解说明

| 注解 | 用途 | 示例 | |------|------|------| | @Api | 描述Controller | @Api(tags = "用户管理") | | @ApiOperation | 描述方法 | @ApiOperation("获取用户列表") | | @ApiParam | 描述参数 | @ApiParam("用户ID") Long id | | @ApiModel | 描述模型 | @ApiModel("用户实体") | | @ApiModelProperty | 描述模型属性 | @ApiModelProperty("用户名") |