不用在写这么多的接口文档-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

相关文章

Java编译生成多个.class文件的原理和作用

《Java编译生成多个.class文件的原理和作用》作为一名经验丰富的开发者,在Java项目中执行编译后,可能会发现一个.java源文件有时会产生多个.class文件,从技术实现层面详细剖析这一现象... 目录一、内部类机制与.class文件生成成员内部类(常规内部类)局部内部类(方法内部类)匿名内部类二、

SpringBoot实现数据库读写分离的3种方法小结

《SpringBoot实现数据库读写分离的3种方法小结》为了提高系统的读写性能和可用性,读写分离是一种经典的数据库架构模式,在SpringBoot应用中,有多种方式可以实现数据库读写分离,本文将介绍三... 目录一、数据库读写分离概述二、方案一:基于AbstractRoutingDataSource实现动态

Springboot @Autowired和@Resource的区别解析

《Springboot@Autowired和@Resource的区别解析》@Resource是JDK提供的注解,只是Spring在实现上提供了这个注解的功能支持,本文给大家介绍Springboot@... 目录【一】定义【1】@Autowired【2】@Resource【二】区别【1】包含的属性不同【2】@

springboot循环依赖问题案例代码及解决办法

《springboot循环依赖问题案例代码及解决办法》在SpringBoot中,如果两个或多个Bean之间存在循环依赖(即BeanA依赖BeanB,而BeanB又依赖BeanA),会导致Spring的... 目录1. 什么是循环依赖?2. 循环依赖的场景案例3. 解决循环依赖的常见方法方法 1:使用 @La

Java枚举类实现Key-Value映射的多种实现方式

《Java枚举类实现Key-Value映射的多种实现方式》在Java开发中,枚举(Enum)是一种特殊的类,本文将详细介绍Java枚举类实现key-value映射的多种方式,有需要的小伙伴可以根据需要... 目录前言一、基础实现方式1.1 为枚举添加属性和构造方法二、http://www.cppcns.co

Elasticsearch 在 Java 中的使用教程

《Elasticsearch在Java中的使用教程》Elasticsearch是一个分布式搜索和分析引擎,基于ApacheLucene构建,能够实现实时数据的存储、搜索、和分析,它广泛应用于全文... 目录1. Elasticsearch 简介2. 环境准备2.1 安装 Elasticsearch2.2 J

使用C#代码在PDF文档中添加、删除和替换图片

《使用C#代码在PDF文档中添加、删除和替换图片》在当今数字化文档处理场景中,动态操作PDF文档中的图像已成为企业级应用开发的核心需求之一,本文将介绍如何在.NET平台使用C#代码在PDF文档中添加、... 目录引言用C#添加图片到PDF文档用C#删除PDF文档中的图片用C#替换PDF文档中的图片引言在当

详解C#如何提取PDF文档中的图片

《详解C#如何提取PDF文档中的图片》提取图片可以将这些图像资源进行单独保存,方便后续在不同的项目中使用,下面我们就来看看如何使用C#通过代码从PDF文档中提取图片吧... 当 PDF 文件中包含有价值的图片,如艺术画作、设计素材、报告图表等,提取图片可以将这些图像资源进行单独保存,方便后续在不同的项目中使

Java中的String.valueOf()和toString()方法区别小结

《Java中的String.valueOf()和toString()方法区别小结》字符串操作是开发者日常编程任务中不可或缺的一部分,转换为字符串是一种常见需求,其中最常见的就是String.value... 目录String.valueOf()方法方法定义方法实现使用示例使用场景toString()方法方法

Java中List的contains()方法的使用小结

《Java中List的contains()方法的使用小结》List的contains()方法用于检查列表中是否包含指定的元素,借助equals()方法进行判断,下面就来介绍Java中List的c... 目录详细展开1. 方法签名2. 工作原理3. 使用示例4. 注意事项总结结论:List 的 contain