不用在写这么多的接口文档-SpringBoot整合Swagger,解放你打接口文档的双手

本文主要是介绍不用在写这么多的接口文档-SpringBoot整合Swagger,解放你打接口文档的双手,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

今天学习了一下Swagger的继承文档功能

我们为什么要使用Swagger呢?

在前后端通过分离的方式开发项目时,我们作为后端程序员,需要给予前端各种各样的接口,但是前端是不懂得代码的,所以我们在进行接口开发之后,还需要为接口写入一个文档,单独为接口介绍,使得前端人员能够通过此介绍方式在前端页面能够调用我们后台的控制器,而有时候在开发时,因为某些因素的变化,我们就需要对接口进行改变,那时,我们又需要重新修改接口并且还要重写我们给与前端的接口介绍文档,这样就使得我们的开发变得十分的麻烦,因此,Swagger框架就为此功能而生成了。

在使用Swagger的之前,我们首先使用手写的接口介绍尝试一次

--------------------------------------------------------------------------

接口:用户登录

接口路径:localhost:9999/dologin

请求参数:userName,password

参数名称参数类型注释
userNameString用户名
passwordString密码

请求方式:post

返回的数据结构

1 或者 2

1表示登录成功在数据库中有数据

2表示登录失败在数据库中没有数据

参数说明:

参数名称参数类型注释
IntegerInteger返回1表示登录成功 2表示登录失败

接口:删除用户

接口路径:localhost:9999/removeUser

请求参数:id

参数名称参数类型注释
idInteger用户的id编号

请求方式:get

返回的数据结构:

Integer

1或者0

参数说明

返回参数名称参数类型注释
Integer数据Integer返回1表示删除成功

接口:查询学生

接口路径:localhost:9004/student

请求参数:无

请求方式:get

返回的数据结构:

[{"studentNo": 1,"studentName": "张三","studentAge": 18,"studentSex": "男"},{"studentNo": 2,"studentName": "小花","studentAge": 17,"studentSex": "女"},{"studentNo": 3,"studentName": "小鲸鱼","studentAge": 10,"studentSex": "女"},{"studentNo": 4,"studentName": "大鲨鱼","studentAge": 16,"studentSex": "男"},{"studentNo": 5,"studentName": "大脑虎","studentAge": 20,"studentSex": "男"}
]

参数说明

参数名称参数类型注释
studentNoInteger学生编号
studentNameString姓名
studentAgeString年龄
studentSexString性别

接口:返回一个map集合

接口路径:localhost:9004/map

请求参数:无

请求方式:get

返回的数据结构:

{
"其一":“劝君莫惜金缕衣,劝君须惜少年时。有花堪折直须折,莫待无花空折枝。”,
"金缕衣":“杜秋娘”,
"其二":"青天无云月如烛,露泣梨花白如玉。 子规一夜啼到明,美人独在空房宿。"
}

参数说明

返回参数名称参数类型注释
map的key值String返回map集合的key值
map的value值String返回map集合的value值

---------------------------------------------------------------------------

本次我写入了四个接口介绍 感觉十分的麻烦,并且在写的过程中也遇到过代码不小心错误的问题。而这些问题如果是放到上百个接口以上的项目时,就容易极大的增加我们的工作量,这时,Swagger的好处就体现出来了。

使用 Swagger 集成文档具有以下几个优势:

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

使用Swagger:

1.添加他的相关依赖

WEB依赖

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId>
</dependency>

swagger依赖,这里选择 2.9.2 版本。

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

添加配置类

添加一个swagger 配置类,在工程下新建 config 包并添加一个 SwaggerConfig 配置类。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket createRestApi(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build();}private ApiInfo apiInfo(){return new ApiInfoBuilder().title("Kitty API Doc").description("This is a restful api document of Kitty.").version("1.0").build();}}

在添加完配置文件后,即代表Swagger已经配置成功了,我们接下来就

添加一个控制器 测试一下Swagger

添加一个控制器,在工程下新建 controller包并添加一个 HelloController控制器。

HelloController.java

package com.louis.springboot.demo.controller;import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;/* 类注解 */
@Api(value = "desc of class")
@RestController
public class HelloController {/* 方法注解 */@ApiOperation(value = "desc of method", notes = "")@GetMapping(value="/hello")public Object hello( /* 参数注解 */ @ApiParam(value = "desc of param" , required=true ) @RequestParam String name) {return "Hello " + name + "!";}
}

添加完成后,我们启动一下项目

启动完成后

我们在浏览器中收入我们的http://localhost:8080/swagger-ui.html#/
加入swagger-ui中 可以看到我们创建的控制器就在此页面呈现了出来

在这里插入图片描述

这样,我们创建的控制器的文档就这样显示出来了,并且我们可以直接在该页面使用我们的控制器进行各种测试。十分方便。

这篇关于不用在写这么多的接口文档-SpringBoot整合Swagger,解放你打接口文档的双手的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/779310

相关文章

SpringBoot UserAgentUtils获取用户浏览器的用法

《SpringBootUserAgentUtils获取用户浏览器的用法》UserAgentUtils是于处理用户代理(User-Agent)字符串的工具类,一般用于解析和处理浏览器、操作系统以及设备... 目录介绍效果图依赖封装客户端工具封装IP工具实体类获取设备信息入库介绍UserAgentUtils

Spring 中的循环引用问题解决方法

《Spring中的循环引用问题解决方法》:本文主要介绍Spring中的循环引用问题解决方法,本文给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友参考下吧... 目录什么是循环引用?循环依赖三级缓存解决循环依赖二级缓存三级缓存本章来聊聊Spring 中的循环引用问题该如何解决。这里聊

Java学习手册之Filter和Listener使用方法

《Java学习手册之Filter和Listener使用方法》:本文主要介绍Java学习手册之Filter和Listener使用方法的相关资料,Filter是一种拦截器,可以在请求到达Servl... 目录一、Filter(过滤器)1. Filter 的工作原理2. Filter 的配置与使用二、Listen

Spring Boot中JSON数值溢出问题从报错到优雅解决办法

《SpringBoot中JSON数值溢出问题从报错到优雅解决办法》:本文主要介绍SpringBoot中JSON数值溢出问题从报错到优雅的解决办法,通过修改字段类型为Long、添加全局异常处理和... 目录一、问题背景:为什么我的接口突然报错了?二、为什么会发生这个错误?1. Java 数据类型的“容量”限制

Java对象转换的实现方式汇总

《Java对象转换的实现方式汇总》:本文主要介绍Java对象转换的多种实现方式,本文通过实例代码给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友参考下吧... 目录Java对象转换的多种实现方式1. 手动映射(Manual Mapping)2. Builder模式3. 工具类辅助映

SpringBoot请求参数接收控制指南分享

《SpringBoot请求参数接收控制指南分享》:本文主要介绍SpringBoot请求参数接收控制指南,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教... 目录Spring Boot 请求参数接收控制指南1. 概述2. 有注解时参数接收方式对比3. 无注解时接收参数默认位置

SpringBoot基于配置实现短信服务策略的动态切换

《SpringBoot基于配置实现短信服务策略的动态切换》这篇文章主要为大家详细介绍了SpringBoot在接入多个短信服务商(如阿里云、腾讯云、华为云)后,如何根据配置或环境切换使用不同的服务商,需... 目录目标功能示例配置(application.yml)配置类绑定短信发送策略接口示例:阿里云 & 腾

SpringBoot项目中报错The field screenShot exceeds its maximum permitted size of 1048576 bytes.的问题及解决

《SpringBoot项目中报错ThefieldscreenShotexceedsitsmaximumpermittedsizeof1048576bytes.的问题及解决》这篇文章... 目录项目场景问题描述原因分析解决方案总结项目场景javascript提示:项目相关背景:项目场景:基于Spring

Spring Boot 整合 SSE的高级实践(Server-Sent Events)

《SpringBoot整合SSE的高级实践(Server-SentEvents)》SSE(Server-SentEvents)是一种基于HTTP协议的单向通信机制,允许服务器向浏览器持续发送实... 目录1、简述2、Spring Boot 中的SSE实现2.1 添加依赖2.2 实现后端接口2.3 配置超时时

Spring Boot读取配置文件的五种方式小结

《SpringBoot读取配置文件的五种方式小结》SpringBoot提供了灵活多样的方式来读取配置文件,这篇文章为大家介绍了5种常见的读取方式,文中的示例代码简洁易懂,大家可以根据自己的需要进... 目录1. 配置文件位置与加载顺序2. 读取配置文件的方式汇总方式一:使用 @Value 注解读取配置方式二