spring-boot-route(五)整合Swagger生成接口文档

目前,大多数公司都采用了前后端分离的开发模式,为了解决前后端人员的沟通问题,后端人员在开发接口的时候会选择使用swagger2来生成对应的接口文档,swagger2提供了强大的页面调试功能,这样可以有效解决前后端人员沟通难的问题。

下面我们使用SpringBoot结合swagger2生成Restful API文档。

一 搭建项目,引入依赖

新建一个spring-boot-swaager的项目,引入swaager2的依赖,由于swagger2的ui不是很美观,这里将使用开源的swagger-bootstrap-ui做为ui。

引入依赖

<!-- swaager2依赖 -->    
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- swaager2ui -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

项目中配置swagger相关信息

@Configuration
@EnableSwagger2
public class configuration {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.javatrip.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                // 标题
                .title("某某项目接口文档")
                // 描述
                .description("swagger2接口文档使用演示")
                // 版本
                .version("1.0")
                // 许可证
                .license("MIT")
                // 许可证地址
                .licenseUrl("www.xx.com")
                // 服务端地址
                .termsOfServiceUrl("https://www.cnblogs.com/zhixie/")
                // 联系信息
                .contact(new Contact("java旅途","https://www.cnblogs.com/zhixie/","binzh303@163.com"))
                .build();
    }
}

访问路径,查看生成效果

文章中使用的这个ui,接口文档地址为ip:port/doc.html,生成的文档信息如下:

二 编写Restful接口

新建实体类

@ApiModel("用户实体类")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Person {
    @ApiModelProperty("姓名")
    private String name;
    @ApiModelProperty(value = "年龄")
    private int age;
}

新建Restful接口

@Api(tags = "用户接口")
@RestController
@RequestMapping("person")
public class PersonController {

    @ApiOperation(value = "获取用户列表",notes = "根据name获取用户列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name",value = "用户姓名",dataType = "String",required = true),
            @ApiImplicitParam(name = "age",value = "年龄",dataType = "int",required = true)
    })
    @GetMapping("/{name}")
    public Person getPerson(@PathVariable("name") String name,@RequestParam int age){
        return new Person(name,age);
    }

    @ApiOperation(value = "新增用户",notes = "根据用户实体类新增用户")
    @ApiImplicitParam(name = "person",value = "用户实体类",dataType = "Person",required = true)
    @PostMapping("add")
    public int addPerson(@RequestBody Person person){
        if(StringUtils.isEmpty(person)){
            return -1;
        }
        return 1;
    }

    @ApiOperation(value = "更新用户信息",notes = "根据用户实体更新用户信息")
    @ApiImplicitParam(name = "person",value = "用户实体类",dataType = "Person",required = true)
    @PutMapping("update")
    public int updatePerson(@RequestBody Person person){
        if(StringUtils.isEmpty(person)){
            return -1;
        }
        return 1;
    }

    @ApiOperation(value = "删除用户信息",notes = "根据用户名删除用户信息")
    @ApiImplicitParam(name = "name",value = "用户姓名",dataType = "String",required = true)
    @DeleteMapping("/{name}")
    public int deletePerson(@PathVariable(name = "name") String name){
        if(StringUtils.isEmpty(name)){
            return -1;
        }
        return 1;
    }
}

三 swagger文档简介

我就直接用图来表示了,这样看着也更加直观

swagger2注解对应到文档上的表现形式如上。swagger2支持在线调试,打开某个具体的接口,根据提示填写对应的参数,点击发送就可返回响应结果。


本文示例代码已上传至github,点个star支持一下!

Spring Boot系列教程目录

spring-boot-route(一)Controller接收参数的几种方式

spring-boot-route(二)读取配置文件的几种方式

spring-boot-route(三)实现多文件上传

spring-boot-route(四)全局异常处理

spring-boot-route(五)整合swagger生成接口文档

spring-boot-route(六)整合JApiDocs生成接口文档

spring-boot-route(七)整合jdbcTemplate操作数据库

spring-boot-route(八)整合mybatis操作数据库

spring-boot-route(九)整合JPA操作数据库

spring-boot-route(十)多数据源切换

spring-boot-route(十一)数据库配置信息加密

spring-boot-route(十二)整合redis做为缓存

spring-boot-route(十三)整合RabbitMQ

spring-boot-route(十四)整合Kafka

spring-boot-route(十五)整合RocketMQ

spring-boot-route(十六)使用logback生产日志文件

spring-boot-route(十七)使用aop记录操作日志

spring-boot-route(十八)spring-boot-adtuator监控应用

spring-boot-route(十九)spring-boot-admin监控服务

spring-boot-route(二十)Spring Task实现简单定时任务

spring-boot-route(二十一)quartz实现动态定时任务

spring-boot-route(二十二)实现邮件发送功能

spring-boot-route(二十三)开发微信公众号

spring-boot-route(二十四)分布式session的一致性处理

spring-boot-route(二十五)两行代码实现国际化

spring-boot-route(二十六)整合webSocket

这个系列的文章都是工作中频繁用到的知识,学完这个系列,应付日常开发绰绰有余。如果还想了解其他内容,扫面下方二维码告诉我,我会进一步完善这个系列的文章!

posted @ 2020-10-06 00:13  Java旅途  阅读(863)  评论(0编辑  收藏  举报