SpringBoot整合Swagger-ui快速生成在线API文档

SpringBoot整合Swagger-ui实现在线API文档

Swagger是一款功能强大的api框架,支持在线接口文档的ui界面,还提供了在线测试功能,此外,它还支持流行的Restful风格接口。

本篇要点

  • 简单介绍restful风格。

  • 介绍SpringBoot与Swagger-ui快速整合。

  • 介绍Swagger-ui常用注解。

一、restful风格简单介绍

REST(Representational State Transfer):表述性状态传递,它是一种针对网络应用的设计和开发方式,可以降低开发的复杂性,提高系统的可伸缩性。

简单来说,HTTP协议本身是无状态的协议,客户端想要操作服务器,可以通过请求资源的方式,将"状态"进行传递。

  • GET请求表示获取资源。
  • POST请求表示新建资源。
  • PUT请求表示更新资源。
  • DELETE请求表示删除资源。

二、SpringBoot与Swagger-ui快速整合

1、第一种方式:使用官方依赖

一、导入依赖

        <properties>
        <swagger.version>2.9.2</swagger.version>
    	</properties> 

        <!--swagger2官方依赖-->
		<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>

二、编写Swagger的配置文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .pathMapping("/")
                .select()
           		 //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("com.hyh.fireworks.web"))
                // 为有@Api注解的Controller生成API文档
                //.apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) 
                // 为有@ApiOperation注解的方法生成API文档
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger接口文档")
                .description("Fireworks 博客网站 接口文档 ")
                .contact(new Contact("天乔巴夏","https://www.hyhwky.com","1332790762@qq.com"))
                .version("1.0")
                .build();
    }
}

三、在实体类model上应用注解

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "User对象",description = "用户表")
public class User implements Serializable {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty(value = "id")
    private Integer id;

    @ApiModelProperty(value = "用户名")
    private String name;

    @ApiModelProperty(value = "年龄")
    private Integer age;
}

四、在接口上应用注解

注:以下注解不加也是可以测试成功的,不过为了文档的可读性,建议加上方法注释。

@Api(tags = "User控制器") //修饰整个类,描述Controller的作用
@RestController
@RequestMapping("/users")
public class UserController {

    private static final List<User> USERS = new ArrayList<>();

    static {
        USERS.add(new User(1,"hyh",12));
        USERS.add(new User(2,"summer day",18));
        USERS.add(new User(3,"天乔巴夏",20));
    }

    @GetMapping("/{id}")
    @ApiOperation("获取指定user")
    public User getUser(@PathVariable @ApiParam(value = "id",required = true,defaultValue = "3") Integer id){
        return USERS.get(id - 1);
    }

    @DeleteMapping("/{id}")
    @ApiOperation("删除指定user")
    @ApiImplicitParam(name = "id",value = "user id",dataType = "Integer",paramType = "path")
    public String deleteUser(@PathVariable Integer id){
        USERS.remove(id - 1);
        return "success";
    }

    @PostMapping()
    @ApiOperation("新增用户")
    public String postUser(@RequestBody User user){
        USERS.add(user);
        return "success";
    }

    @PutMapping("/{id}")
    @ApiOperation("更新用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "id",paramType = "path"),@ApiImplicitParam(name = "user",value = "user 实体",dataType = "User")
    })
    public String putUser(@PathVariable Integer id,@RequestBody User user){
        user.setId(id);
        USERS.set(id - 1,user);
        return "success";
    }

    @GetMapping()
    @ApiOperation("用户列表")
    public List<User> getUsers(){
        return USERS;
    }

    @ApiIgnore //生成接口文档时,忽略该接口
    @GetMapping("/ignore")
    public String ignoreTest(){
        return "ignore";
    }
}

五、访问http://localhost:8081/swagger-ui.html即可看到效果

2、第二种方式:使用第三方依赖

文档及源码地址:https://github.com/SpringForAll/spring-boot-starter-swagger,内有详细文档说明,利用Spring Boot的自动化配置特性来实现快速的将swagger2引入spring boot应用来生成API文档,简化原生使用swagger2的整合代码。

感兴趣的小伙伴可以照着文档上的demo自己测试一下哈。

三、swagger-ui的基本注解

  • @Api:用于修饰Controller
  • @ApiOperation:用于修饰Controller类中的方法
  • @ApiParam:用于修饰接口中的参数
  • @ApiModelProperty:用于修饰实体类的属性

源码下载

本文内容均为对优秀博客及官方文档总结而得,原文地址均已在文中参考阅读处标注。最后,文中的代码样例已经全部上传至Gitee:https://gitee.com/tqbx/springboot-samples-learn,另有其他SpringBoot的整合哦。

参考阅读

版权声明:本文内容由互联网用户自发贡献,该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 dio@foxmail.com 举报,一经查实,本站将立刻删除。

相关推荐


今天小编给大家分享的是Springboot下使用Redis管道(pipeline)进行批量操作的介绍,相信很多人都不太了解,为了让大家更加了解,所以给大家总结了以下内容,一起...
本篇文章和大家了解一下springBoot项目常用目录有哪些。有一定的参考价值,有需要的朋友可以参考一下,希望对大家有所帮助。springBoot项目常用目录springBoot项...
本篇文章和大家了解一下Springboot自带线程池怎么实现。有一定的参考价值,有需要的朋友可以参考一下,希望对大家有所帮助。一: ThreadPoolTaskExecuto1 ThreadP...
这篇文章主要介绍了SpringBoot读取yml文件有哪几种方式,具有一定借鉴价值,需要的朋友可以参考下。下面就和我一起来看看吧。Spring Boot读取yml文件的主要方式...
今天小编给大家分享的是SpringBoot配置Controller实现Web请求处理的方法,相信很多人都不太了解,为了让大家更加了解,所以给大家总结了以下内容,一起往下看吧...
本篇文章和大家了解一下SpringBoot实现PDF添加水印的方法。有一定的参考价值,有需要的朋友可以参考一下,希望对大家有所帮助。简介PDF(Portable Document Form...
本篇文章和大家了解一下解决Springboot全局异常处理与AOP日志处理中@AfterThrowing失效问题的方法。有一定的参考价值,有需要的朋友可以参考一下,希望对大家有...
本篇文章和大家了解一下IDEA创建SpringBoot父子Module项目的实现方法。有一定的参考价值,有需要的朋友可以参考一下,希望对大家有所帮助。目录前言1. 软硬件环...
今天小编给大家分享的是springboot获取项目目录路径的方法,相信很多人都不太了解,为了让大家更加了解,所以给大家总结了以下内容,一起往下看吧。一定会有所收...
本篇内容主要讲解“SpringBoot+Spring Security无法实现跨域如何解决”,感兴趣的朋友不妨来看看。本文介绍的方法操作简单快捷,实用性强。下面...
这篇文章主要介绍“vue怎么发送请求到springboot程序”,在日常操作中,相信很多人在vue怎么发送请求到springboot程序问题上存在疑惑,小编查阅了各式资料,整理...
本篇内容主要讲解“Springboot内置的工具类CollectionUtils如何使用”,感兴趣的朋友不妨来看看。本文介绍的方法操作简单快捷,实用性强。下面就让小编来带大家...
本文小编为大家详细介绍“SpringBoot上传文件大小受限如何解决”,内容详细,步骤清晰,细节处理妥当,希望这篇“SpringBoot上传文件大小受限如何解决”文章能帮...
本文小编为大家详细介绍“springboot拦截器如何创建”,内容详细,步骤清晰,细节处理妥当,希望这篇“springboot拦截器如何创建”文章能帮助大家解决疑惑,下面...
本文小编为大家详细介绍“Hikari连接池使用SpringBoot配置JMX监控的方法是什么”,内容详细,步骤清晰,细节处理妥当,希望这篇“Hikari连接池使用SpringBoot配...
今天小编给大家分享一下SpringBoot如何使用Sa-Token实现权限认证的相关知识点,内容详细,逻辑清晰,相信大部分人都还太了解这方面的知识,所以分享这篇文章给大...
这篇文章主要介绍“SpringBoot如何集成SFTP客户端实现文件上传下载”,在日常操作中,相信很多人在SpringBoot如何集成SFTP客户端实现文件上传下...
本篇内容主要讲解“Springboot插件怎么开发”,感兴趣的朋友不妨来看看。本文介绍的方法操作简单快捷,实用性强。下面就让小编来带大家学习“Springboot插件怎
这篇文章主要介绍“Springboot怎么解决跨域请求问题”的相关知识,小编通过实际案例向大家展示操作过程,操作方法简单快捷,实用性强,希望这篇...
今天小编给大家分享一下如何在SpringBoot2中整合Filter的相关知识点,内容详细,逻辑清晰,相信大部分人都还太了解这方面的知识,所以分享这篇文...