正文

springboot集成swagger2在线文档

supergan  2022-05-18  521

关键词：

SpringBoot集成Swagger2在线文档

SpringBoot集成Swagger2在线文档

前言

不得不说，前后端分离开发的工作方式给我们带来诸多好处，让前后端攻城狮们顺畅了不少

技术图片

后端给前端提供良好的接口文档是一种品质，也会减少彼此的沟通成本

技术图片

这里推荐小伙伴们一款在线、实时更新接口文档工具，Swagger2，解放双手不是梦，谁用谁知道

集成SpringBoot

添加依赖

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

创建配置文件Swagger2Config.java

@Configuration
@EnableSwagger2
public class Swagger2Config {

     // 项目启动后，查看文档：http://{上下方路径}/swagger-ui.html
    // 如，http://localhost:8080/swagger-ui.html

    // Swagger2 核心配置 docket
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)  // 指定api类型
                .apiInfo(createApiInfo())               //定义文档汇总信息
                .select().apis(RequestHandlerSelectors
                        .basePackage("cn.supergan.controller")) //指定controller包
                .paths(PathSelectors.any()) //所有controller
                .build();
    }

     // 构建文档信息
    public ApiInfo createApiInfo() {
        return new ApiInfoBuilder()
                .title("XXX 接口API")   //文档页标题
                .contact(new Contact("小动物不困", "https://www.supergan.cn", "abc@email.com"))   //联系人信息
                .description("XXX 接口API，实时更新，如有问题，及时沟通") //详细信息
                .version("1.0")   //文档版本号
                .termsOfServiceUrl("https://www.supergan.cn")    //网站地址
                .build();
    }
}

启动项目，访问文档首页http://localhost:8080/swagger-ui.html，效果如下

登录接口文档示例

代码

接口类：PassportController.java

@Api(tags = "登录")
@RestController
public class PassportController {

@ApiOperation(value = "登录", notes = "使用用户名和密码登录")
@ApiImplicitParams({
        @ApiImplicitParam(value = "用户名", name = "username", required = true),
        @ApiImplicitParam(value = "密码", name = "password", required = true)
})
@PostMapping("/login")
public JSONResult<Users> login(@RequestParam String username, @RequestParam String password) {
    Users users = new Users();
    // TODO 此处省略登录相关业务逻辑
    users.setUsername(username);
    users.setPassword(password);
    return JSONResult.ok(users);
}

用户类：Users.java

@ApiModel(description = "用户")
@Data
public class Users {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
}

响应类：JSONResult.java，统一接口的数据响应格式，小伙伴们可根据自己的需求改造和使用

@Data
public class JSONResult<T> {
    private Integer status;
    private String message;
    private T data;

    public JSONResult(ResultCode code) {
        this.setMessage(code.getMessage());
        this.setStatus(code.getStatus());
    }

    public static <T> JSONResult<T> ok(T data) {
        JSONResult<T> jsonResult = new JSONResult<T>(ResultCode.SUCCESS);
        jsonResult.setData(data);
        return jsonResult;
    }

    @Getter
    enum ResultCode {
        SUCCESS(200, "OK"),
        UN_KNOW_ERROR(500, "未知异常")
        ;
        private Integer status;
        private String message;

        ResultCode(Integer status, String message) {
            this.status = status;
            this.message = message;
        }
    }
}

效果

技术图片

注解说明

@Api

@Api：用在请求的类上，说明该类的作用
    tags="说明该类的作用"
    value="该参数没什么意义，所以不需要配置"
  
示例
@Api(tags="APP用户注册Controller")

@ApiOperation

@ApiOperation：用在请求的方法上，说明方法的作用
    value="说明方法的作用"
    notes="方法的备注说明"
  
示例
@ApiOperation(value = "登录", notes = "使用用户名和密码登录")

@ApiImplicitParams

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
    @ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息       
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

示例
@ApiImplicitParams({
        @ApiImplicitParam(value = "用户名", name = "username", required = true),
        @ApiImplicitParam(value = "密码", name = "password", required = true)
})

@ApiResponses

@ApiResponses：用于请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

示例
@ApiResponses({
    @ApiResponse(code=400,message="请求参数错误"),
    @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})

@ApiModel

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性
  
示例
@ApiModel(description = "用户")
@Data
public class Users {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
}

总结

本文介绍了在SpringBoot中如何集成Swagger2，快速上手的用法，和主要注解的说明。

其中值得注意的是，上文中提到的JSONResult.java，它的泛型申明，在接口文档中起到了描述data属性详情的作用。

以上内容足以让你在日常开发中轻松驾驭Swagger2

springboot系列(十七):集成在线接口文档swagger2|超级详细，建议收藏(代码片段)

👨‍🎓作者：bug菌🎉简介：在CSDN、掘金等社区优质创作者，全网合计6w粉+，对一切技术都感兴趣，重心偏java方向，目前运营公众号[猿圈奇妙屋]，欢迎小伙伴们的加入，一起秃头。... 查看详情

企业级springboot教程springboot集成swagger2，构建优雅的restfulapi

swagger,中文“拽”的意思。它是一个功能强大的api框架，它的集成非常简单，不仅提供了在线文档的查阅，而且还提供了在线文档的测试。另外swagger很容易构建restful风格的api，简单优雅帅气，正如它的名字。一、引入依赖<depe... 查看详情

springboot集成swagger2

...c;尽早解决”，最终导致问题集中爆发。3 方法1.新建SpringBoot-web项目2.导入Swagger2依赖<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> &l 查看详情

springboot整合swagger2搭建api在线文档

...阅和测试功能。利用Swagger2很容易构建RESTful风格的API，在SpringBoot中集成Swagger2，步骤如下。1.引入依赖<dependency><groupId> 查看详情

springboot之swagger2集成

一、Swagger2简单介绍　　Swagger2，它可以轻松的整合到SpringBoot中，并与SpringMVC程序配合组织出强大RESTfulAPI文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以... 查看详情

springboot集成swagger2生成api接口文档(代码片段)

SpringBoot2.3.0集成Swagger2引入Swagger2相应的依赖入门示例SpringBoot2集成Swagger2后启动报错结语背景：最近在工作中发现，已经多次发现后台开发人员提供的接口协议和实际的业务代码不统一。这些现象往往都是因为开发人员在... 查看详情

springboot集成swagger2(代码片段)

1、swagger简介　　Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，加上swagger-ui，可以有很好的呈现。　　当我们在后台的接口修... 查看详情

springboot2系列教程|集成swagger2构建强大的restfulapi文档

...。反正我是挺闲的，所以有时间写blog。今天给你们带来SpringBoot集成Swagger2的教程。什么是Swagger2Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。为什么使用Swagger2？相信刚开始不熟悉web开发... 查看详情

springboot集成swagger2生成api接口文档(代码片段)

springboot2.0系列教程springboot框架添加swagger2来在线自动生成接口的文档+测试功能(代码片段)

Hello大家好，本章我们添加Swagger2来在线自动生成接口的文档+测试功能。有问题可以联系我[email protected]。另求各路大神指点，感谢一：什么是SwaggerSwagger是一款通过我们添加的注解来对方法进行说明，来自动生成项目的在线a... 查看详情

springboot1.5.4集成swagger2构建restfulapi（十八）

上一篇博客地址：springboot1.5.4整合rabbitMQ（十七）1 SpringBoot集成Swagger2构建RESTfulAPI文档1.1 Swagger2简介Swagger2官网：http://swagger.io/由于SpringBoot能够快速开发、便捷部署等特性，相信有很大一部分SpringBoo 查看详情

javaspringboot微服务b2b2c电子商务系统-springboot集成swagger2，构建优雅的restfulapi

第05章—swagger2打造在线接口文档

springboot系列学习记录：http://www.cnblogs.com/jinxiaohang/p/8111057.html码云源码地址：https://gitee.com/jinxiaohang/springboot 一、添加Swagger2依赖 <dependency><groupId>io.s 查看详情

springboot项目集成swagger2

一、前言现如今，前后端分离已经逐渐成为互联网项目一种标准的开发方式，前端与后端交给不同的人员开发，但是项目开发中的沟通成本也随之升高，这部分沟通成本主要在于前端开发人员与后端开发人员对WebAPI接口的沟通，... 查看详情

springboot整合swagger2

SpringBoot整合Swagger2相信各位在公司写API文档数量应该不少，当然如果你还处在自己一个人开发前后台的年代，当我没说，如今为了前后台更好的对接，还是为了以后交接方便，都有要求写API文档。手写Api文档的几个痛点：文档需... 查看详情

springboot整合swagger2

　　手写Api文档的几个痛点：文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。接口返回结果不明确不能直接在线测试接口，通常需要使用工具，比如postman接口文档太多，不好管理　　Swagger也就是... 查看详情

spring集成swagger2,提供restfulapi

...绍RESTfulAPI的重磅好伙伴Swagger2，它可以轻松的整合到SpringBoot中，并与SpringMVC程序配合组织出强大RESTfulAPI文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整... 查看详情

springboot入门：集成swagger2

本片文章是基于前一篇写的，《SpringBoot入门（六）：集成treetable和zTree实现树形图》，本篇主要介绍了springboot集成swagger2。关于swagger的介绍，自行谷歌。我这里有在网上购买的相关视频资料，有需要可以呼叫我。1.引入相关依赖... 查看详情