微服务技术系列教程(26) - SpringCloud- 接口管理Swagger

简介: 微服务技术系列教程(26) - SpringCloud- 接口管理Swagger

引言

代码已提交到Github,有兴趣的同学可以看看:https://github.com/ylw-github/SpringCloud-Zuul-Demo/tree/master/repository/Swagger-Demo

随着微服务架构体系的发展和应用, 为了前后端能够更好的集成与对接,同时为了项目的方便交付,每个项目都需要提供相应的API文档。

提供的对象有PC端、微信端、H5端、移动端(安卓和IOS端)

传统的API文档编写存在以下几个问题:

  • 对API文档进行更新的时候,需要通知前端开发人员,导致文档更新交流不及时;
  • API接口返回信息不明确。
  • 大公司中肯定会有专门文档服务器对接口文档进行更新。
  • 缺乏在线接口测试,通常需要使用相应的API测试工具,比如postman、SoapUI等
  • 接口文档太多,不便于管理。

为了解决传统API接口文档维护的问题,为了方便进行测试后台Restful接口并实现动态的更新,因而引入Swagger接口工具。

1. Swagger

Swagger Demo的代码已提交到Github,有兴趣的同学可以看看:https://github.com/ylw-github/SpringCloud-Zuul-Demo/tree/master/repository/Swagger-Demo

Swagger具有以下优点:

  • 功能丰富:支持多种注解,自动生成接口文档界面,支持在界面测试API接口功能;
  • 及时更新:开发过程中花一点写注释的时间,就可以及时的更新API文档,省心省力;
  • 整合简单:通过添加pom依赖和简单配置,内嵌于应用中就可同时发布API接口文档界面,不需要部署独立服务。

1.1 Swagger集成步骤

1.新建Maven项目Swagger-Demo

2.添加Maven依赖

<parent>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-parent</artifactId>
     <version>2.0.1.RELEASE</version>
 </parent>
 <dependencies>
     <!-- SpringBoot整合Web组件 -->
     <dependency>
         <groupId>org.springframework.boot</groupId>
         <artifactId>spring-boot-starter-web</artifactId>
     </dependency>
     <!--SpringBoot swagger2 -->
     <dependency>
         <groupId>io.springfox</groupId>
         <artifactId>springfox-swagger2</artifactId>
         <version>2.8.0</version>
     </dependency>
     <!--SpringBoot swagger2 -UI -->
     <dependency>
         <groupId>io.springfox</groupId>
         <artifactId>springfox-swagger-ui</artifactId>
         <version>2.8.0</version>
     </dependency>
 </dependencies>

3.添加SwaggerConfig

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                // api扫包
                .apis(RequestHandlerSelectors.basePackage("com.ylw.swagger.api")).paths(PathSelectors.any()).build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("学生信息管理系统").description("对学生信息进行管理")
                .termsOfServiceUrl("http://www.xxx.com")
                // .contact(contact)
                .version("1.0").build();
    }
}

4.API注释

@RestController
@RequestMapping("api")
@Api("学生信息管理系统相关的api")
public class StudentController {
    private static final Logger logger = LoggerFactory.getLogger(StudentController.class);
    @ApiOperation(value = "新增学生信息", notes = "新增学生信息:用户名、性别、年龄")
    @ApiResponses({
            @ApiResponse(code = 200, message = "校验成功"),
            @ApiResponse(code = 400, message = "校验失败"),
            @ApiResponse(code = 401, message = "参数不合法"),
            @ApiResponse(code = 500, message = "系统异常"),
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userName", value = "学生名字", required = true, dataType = "String"),
            @ApiImplicitParam(name = "sex", value = "性别", required = false, dataType = "String"),
            @ApiImplicitParam(name = "age", value = "年龄", required = false, dataType = "Integer"),
    })
    @RequestMapping(value = "/addStudent/{userName}/{sex}/{age}", method = RequestMethod.POST)
    public Response addStudent(@PathVariable String userName, @PathVariable String sex, @PathVariable Integer age) {
        logger.info("新增学生信息操作");
        return new Response(200, "新增学生信息成功!");
    }
    @ApiOperation(value = "删除学生信息", notes = "删除学生信息:用户名、性别、年龄")
    @ApiResponses({
            @ApiResponse(code = 200, message = "校验成功"),
            @ApiResponse(code = 400, message = "校验失败"),
            @ApiResponse(code = 401, message = "参数不合法"),
            @ApiResponse(code = 500, message = "系统异常"),
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "uuid", value = "学生id", required = true, dataType = "String"),
    })
    @RequestMapping(value = "/delStudent/{uuid}", method = RequestMethod.DELETE)
    public Response delStudent(@PathVariable String uuid) {
        logger.info("删除学生信息操作");
        return new Response(200, "删除学生信息成功!");
    }
    @ApiOperation(value = "修改学生信息", notes = "修改学生信息:用户名、性别、年龄")
    @ApiResponses({
            @ApiResponse(code = 200, message = "校验成功"),
            @ApiResponse(code = 400, message = "校验失败"),
            @ApiResponse(code = 401, message = "参数不合法"),
            @ApiResponse(code = 500, message = "系统异常"),
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "学生id", required = true, dataType = "String"),
            @ApiImplicitParam(name = "userName", value = "学生名字", required = true, dataType = "String"),
            @ApiImplicitParam(name = "sex", value = "性别", required = false, dataType = "String"),
            @ApiImplicitParam(name = "age", value = "年龄", required = false, dataType = "Integer"),
    })
    @RequestMapping(value = "/updateStudent/{id}/{userName}/{sex}/{age}", method = RequestMethod.POST)
    public Response updateStudent(@PathVariable String id, @PathVariable String userName, @PathVariable String sex, @PathVariable Integer age) {
        logger.info("修改学生信息操作");
        return new Response(200, "修改学生信息成功!");
    }
    @ApiOperation(value = "查询学生信息", notes = "查询学生信息:用户名、性别、年龄")
    @ApiResponses({
            @ApiResponse(code = 200, message = "校验成功"),
            @ApiResponse(code = 400, message = "校验失败"),
            @ApiResponse(code = 401, message = "参数不合法"),
            @ApiResponse(code = 500, message = "系统异常"),
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "学生id", required = true, dataType = "String"),
    })
    @RequestMapping(value = "/getStudent/{id}", method = RequestMethod.GET)
    public Response getStudent(@PathVariable String id) {
        logger.info("修改学生信息操作");
        return new Response(200, "修改学生信息成功!");
    }
}

5.浏览器访问

访问网址:http://localhost:8099/swagger-ui.html#/,可以看到接口文档自动生成了。

6.展开其中的一个接口

可以看到描述:

目录
相关文章
|
13天前
|
消息中间件 Java 开发者
Spring Cloud微服务框架:构建高可用、分布式系统的现代架构
Spring Cloud是一个开源的微服务框架,旨在帮助开发者快速构建在分布式系统环境中运行的服务。它提供了一系列工具,用于在分布式系统中配置、服务发现、断路器、智能路由、微代理、控制总线、一次性令牌、全局锁、领导选举、分布式会话、集群状态等领域的支持。
55 5
|
24天前
|
负载均衡 Java 开发者
Spring Cloud微服务架构中的配置管理与服务发现
Spring Cloud微服务架构中的配置管理与服务发现
|
22天前
|
关系型数据库 分布式数据库 数据库
PolarDB,阿里云的开源分布式数据库,与微服务相结合,提供灵活扩展和高效管理解决方案。
【7月更文挑战第3天】PolarDB,阿里云的开源分布式数据库,与微服务相结合,提供灵活扩展和高效管理解决方案。通过数据分片和水平扩展支持微服务弹性,保证高可用性,且兼容MySQL协议,简化集成。示例展示了如何使用Spring Boot配置PolarDB,实现服务动态扩展。PolarDB缓解了微服务数据库挑战,加速了开发部署,为云原生应用奠定基础。
163 3
|
22天前
|
消息中间件 负载均衡 Java
最容易学会的springboot gralde spring cloud 多模块微服务项目
最容易学会的springboot gralde spring cloud 多模块微服务项目
|
25天前
|
负载均衡 Java 开发者
细解微服务架构实践:如何使用Spring Cloud进行Java微服务治理
【6月更文挑战第30天】Spring Cloud是Java微服务治理明星框架,整合Eureka(服务发现)、Ribbon(客户端负载均衡)、Hystrix(断路器)、Zuul(API网关)和Config Server(配置中心),提供完整服务治理解决方案。通过Eureka实现服务注册与发现,Ribbon进行负载均衡,Hystrix确保服务容错,Config Server集中管理配置,Zuul则作为API入口统一处理请求。理解和使用Spring Cloud是现代Java开发者的关键技能。
88 2
|
29天前
|
JSON Java 程序员
马程序员2024最新SpringCloud微服务开发与实战 个人学习心得、踩坑、与bug记录Day1最快 最全(2)
马程序员2024最新SpringCloud微服务开发与实战 个人学习心得、踩坑、与bug记录Day1最快 最全(2)
26 3
|
28天前
|
程序员 测试技术 Docker
黑马程序员2024最新SpringCloud微服务开发与实战 个人学习心得、踩坑、与bug记录Day3 全网最全
黑马程序员2024最新SpringCloud微服务开发与实战 个人学习心得、踩坑、与bug记录Day3 全网最全(1)
81 1
|
16天前
|
消息中间件 供应链 Java
实现基于Spring Cloud的事件驱动微服务
实现基于Spring Cloud的事件驱动微服务
|
19天前
|
微服务
SpringCloud01微服务课程导学,微服务功能用户,支付,购物车,积分,优惠卷,短信功能越来越多
SpringCloud01微服务课程导学,微服务功能用户,支付,购物车,积分,优惠卷,短信功能越来越多
|
23天前
|
负载均衡 Java 开发者
Spring Cloud微服务架构中的配置管理与服务发现
Spring Cloud微服务架构中的配置管理与服务发现