后端 API 接口文档 Swagger 使用指南

news2024/11/25 20:28:48

  • 前言
  • 一：swagger是什么？
  • 二：为什么要使用swaager?
    • 2.1:对于后端开发人员来说
    • 2.2:对于前端开发来说
    • 2.3：对于测试
  • 三：如何搭一个swagger
    • 3.1:引入swagger的依赖
    • 3.2：springBoot整合swagger
    • 3.3：swagger的注解
  • 四：在项目中集成swagger
    • 4.1:在controller中使用注解
    • 4.2:访问本地链接
  • 五：使用swagger需要注意的问题
  • 六：总结​​​​​​​ 

作为一个以前后端分离为模式开发小组，我们每隔一段时间都进行这样一个场景：前端人员和后端开发在一起热烈的讨论"哎,你这参数又变了啊","接口怎么又请求不通了啊","你再试试,我打个断点调试一下.."。可以看到在前后端沟通中出现了不少问题。

对于这样的问题,之前一直没有很好的解决方案，直到它的出现，没错...这就是我们今天要讨论的神器:swagger,一款致力于解决接口规范化、标准化、文档化的开源库，一款真正的开发神器。

一：swagger是什么？

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。

这个解释简单点来讲就是说，swagger是一款可以根据resutful风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。

二：为什么要使用swaager?

2.1:对于后端开发人员来说

  • 不用再手写WiKi接口拼大量的参数，避免手写错误
  • 对代码侵入性低，采用全注解的方式，开发简单
  • 方法参数名修改、增加、减少参数都可以直接生效，不用手动维护
  • 缺点：增加了开发成本，写接口还得再写一套参数配置

2.2:对于前端开发来说

  • 后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然
  • 联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位是前端还是后端的问题

2.3：对于测试

  • 对于某些没有前端界面UI的功能，可以用它来测试接口
  • 操作简单，不用了解具体代码就可以操作
  • 操作简单，不用了解具体代码就可以操作

三：如何搭一个swagger

3.1:引入swagger的依赖

目前推荐使用2.7.0版本,因为2.6.0版本有bug，而其他版本又没有经过验证

一：引入Swagger依赖库
<!--引入swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

3.2：springBoot整合swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))  //添加ApiOperiation注解的被扫描
                .paths(PathSelectors.any())
                .build();

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title(”swagger和springBoot整合“).description(”swagger的API文档")
                .version("1.0").build();
    }

}

3.3：swagger的注解

swagger的核心在于注解，接下来就着重讲一下swagger的注解：

四：在项目中集成swagger

4.1:在controller中使用注解

package com.youjia.swagger.controller;

import com.youjia.swagger.constants.CommonConstants;
import com.youjia.swagger.model.Film;
import com.youjia.swagger.model.ResultModel;
import com.youjia.swagger.service.FilmService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.util.CollectionUtils;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import javax.servlet.http.HttpServletRequest;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.List;
import java.util.Objects;

/**
 * @Auther: wyq
 * @Date: 2018/12/29 14:50
 */
@RestController
@Api(value = "电影Controller", tags = { "电影访问接口" })
@RequestMapping("/film")
public class FilmController {

    @Autowired
    private FilmService filmService;

    /**
     * 添加一个电影数据
     *
     * @param
     * @return
     */
    @ApiOperation(value = "添加一部电影")
    @PostMapping("/addFilm")
    @ApiResponses(value = { @ApiResponse(code = 1000, message = "成功"), @ApiResponse(code = 1001, message = "失败"),
            @ApiResponse(code = 1002, response = Film.class,message = "缺少参数") })
    public ResultModel addFilm(@ApiParam("电影名称") @RequestParam("filmName") String filmName,
                               @ApiParam(value = "分数", allowEmptyValue = true) @RequestParam("score") Short score,
                               @ApiParam("发布时间") @RequestParam(value = "publishTime",required = false) String publishTime,
                               @ApiParam("创建者id") @RequestParam("creatorId") Long creatorId) {

        if (Objects.isNull(filmName) || Objects.isNull(score) || Objects.isNull(publishTime) || StringUtils
                .isEmpty(creatorId)) {
            return new ResultModel(ResultModel.failed, "参数错误");
        }
        Film filmPOM = new Film();
        filmPOM.setFilmName(filmName);
        filmPOM.setScore(score);
        DateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd");
        Date publishTimeDate = null;
        try {
            publishTimeDate = simpleDateFormat.parse(publishTime);
        } catch (Exception ex) {
            ex.printStackTrace();
        }
        filmPOM.setPublishTime(publishTimeDate);
        filmPOM.setCreatorId(creatorId);
        Boolean result = filmService.addFilm(filmPOM);
        if (result) {
            return new ResultModel(CommonConstants.SUCCESSMSG);
        }
        return new ResultModel(CommonConstants.FAILD_MSG);
    }

    /**
     * 根据电影名字获取电影
     *
     * @param fileName
     * @return
     */
    @GetMapping("/getFilms")
    @ApiOperation(value = "根据名字获取电影")
    @ApiResponses(value = { @ApiResponse(code = 1000, message = "成功"), @ApiResponse(code = 1001, message = "失败"),
            @ApiResponse(code = 1002, message = "缺少参数") })
    public ResultModel getFilmsByName(@ApiParam("电影名称") @RequestParam("fileName") String fileName) {
        if (StringUtils.isEmpty(fileName)) {
            return CommonConstants.getErrorResultModel();
        }

        List<Film> films = filmService.getFilmByName(fileName);
        if (!CollectionUtils.isEmpty(films)) {
            return new ResultModel(films);
        }
        return CommonConstants.getErrorResultModel();

    }

    /**
     * 根据电影名更新
     *
     * @return
     */
    @PostMapping("/updateScore")
    @ApiOperation(value = "根据电影名修改分数")
    @ApiResponses(value = { @ApiResponse(code = 1000, message = "成功"), @ApiResponse(code = 1001, message = "失败"),
            @ApiResponse(code = 1002, message = "缺少参数") })
    public ResultModel updateFilmScore(@ApiParam("电影名称") @RequestParam("fileName") String fileName,
                                       @ApiParam("分数") @RequestParam("score") Short score) {
        if (StringUtils.isEmpty(fileName) || Objects.isNull(score)) {
            return CommonConstants.getErrorResultModel();
        }

        filmService.updateScoreByName(fileName, score);
        return CommonConstants.getSuccessResultModel();
    }

    /**
     * 根据电影名删除电影
     *
     * @param request
     * @return
     */
    @PostMapping("/delFilm")
    @ApiOperation(value = "根据电影名删除电影")
    @ApiImplicitParams({ @ApiImplicitParam(name = "filmName",
            value = "电影名",
            dataType = "String",
            paramType = "query",
            required = true), @ApiImplicitParam(name = "id", value = "电影id", dataType = "int", paramType = "query") })
    public ResultModel deleteFilmByNameOrId(HttpServletRequest request) {
        //电影名
        String filmName = request.getParameter("filmName");
        //电影id
        Long filmId = Long.parseLong(request.getParameter("id"));

        filmService.deleteFilmOrId(filmName,filmId);


        return CommonConstants.getSuccessResultModel();
    }

    /**
     * 根据id获取电影
     *
     * @param id
     * @return
     */
    @PostMapping("/{id}")
    @ApiOperation("根据id获取电影")
    @ApiImplicitParam(name = "id", value = "电影id", dataType = "long", paramType = "path", required = true)
    public ResultModel getFilmById(@PathVariable Long id) {

        if (Objects.isNull(id)) {
            return CommonConstants.getLessParamResultModel();
        }
        Film film = filmService.getFilmById(id);
        if (Objects.nonNull(film)) {
            return new ResultModel(film);
        }
        return CommonConstants.getErrorResultModel();
    }

    /**
     * 修改整个电影
     *
     * @param film
     * @return
     */
    @PostMapping("/insertFilm")
    @ApiOperation("插入一部电影")
    public ResultModel insertFilm(@ApiParam("电影实体对象") @RequestBody Film film) {
        if (Objects.isNull(film)) {
            return CommonConstants.getLessParamResultModel();
        }
        Boolean isSuccess = filmService.insertFilm(film);
        if (isSuccess) {
            return CommonConstants.getSuccessResultModel();
        }
        return CommonConstants.getErrorResultModel();
    }
}

4.2:访问本地链接

http://localhost:8080/swagger-ui.html#/

可以看出访问的url都很清晰的展示在它最终的页面上，我们打开一个方法：可以看出方法的请求参数清晰的的罗列出来，包括方法的返回值。并且有一个很重要的功能，只需要点下方的try it out就可以进行接口测试，

五：使用swagger需要注意的问题

  • 对于只有一个HttpServletRequest参数的方法,如果参数小于5个，推荐使用 @ApiImplicitParams的方式单独封装每一个参数；如果参数大于5个，采用定义一个对象去封装所有参数的属性，然后使用@APiParam的方式
  • 默认的访问地址：ip:port/swagger-ui.html#/,但是在shiro中,会拦截所有的请求，必须加上默认访问路径（比如项目中，就是ip:port/context/swagger-ui.html#/），然后登陆后才可以看到
  • 在GET请求中，参数在Body体里面,不能使用@RequestBody。在POST请求，可以使用@RequestBody和@RequestParam，如果使用@RequestBody，对于参数转化的配置必须统一
  • controller必须指定请求类型，否则swagger会把所有的类型(6种)都生成出来
  • swagger在生产环境不能对外暴露,可以使用@Profile({“dev”, “prod”,“pre”})指定可以使用的环境

六：总结

swagger作为一款辅助性的工具，能大大提升我们的和前端的沟通效率,接口是一个非常重要的传递数据的媒介，每个接口的签名、方法参数都非常重要。一个良好的文档非常重要，如果采用手写的方式非常容易拼写错误，而swagger可以自动化生成参数文档，这一切都加快了我们的沟通效率。并且可以替代postman的作用。实在是开发编程必备良品啊。

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.coloradmin.cn/o/587662.html

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈，一经查实，立即删除！

相关文章

Hive介绍

Hive介绍

Hive定义 Hive是一个基于Hadoop的数据仓库工具&#xff0c;可以将结构化的数据文件映射成一张数据表&#xff0c;并可以使用类似SQL的方式来对数据文件进行读写以及管理。这套Hive SQL 简称HQL。Hive的执行引擎可以是MR、Spark、Tez。 Hive的本质是将HQL转换成MapReduce任务&…
阅读更多...
阿里云服务器最新优惠价格及最新收费标准（2023更新）

阿里云服务器最新优惠价格及最新收费标准（2023更新）

阿里云服务器收费标准分为包年包月和按量付费两种模式&#xff0c;包年包月是一种先付费后使用的计费方式&#xff0c;按量付费是一种先使用后付费的计费方式。选择包年包月的收费模式&#xff0c;用户可以提前预留资源&#xff0c;同时享受更大的价格优惠&#xff0c;帮您更大…
阅读更多...
MGRE 综合实验

MGRE 综合实验

配置IP的地址 [R1-GigabitEthernet0/0/0]int g0/0/0 [R1-GigabitEthernet0/0/0]ip add 192.168.1.1 24 [R1-GigabitEthernet0/0/0]int s4/0/0 [R1-Serial4/0/0]ip add 15.0.0.1 24 [R2]int s 4/0/0 [R2-Serial4/0/0]ip add 25.0.0.1 24 [R2-Serial4/0/0]int g 0/0/0 [R2-Giga…
阅读更多...
SpringBatch的两种实现方式: Tasklet 和 Chunk

SpringBatch的两种实现方式: Tasklet 和 Chunk

直接上代码 ■ 共通部分&#xff1a; 1. 代码结构 2. pom.xml <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-batch</artifactId></dependency> 3. framework/BatchAnnotation.java packa…
阅读更多...
MSP432学习笔记8：定时器A_PWM驱动舵机

MSP432学习笔记8：定时器A_PWM驱动舵机

开发板型号&#xff1a;MSP432P401r 今日得以继续我的MSP432电赛速通之路&#xff0c;文首提供本次学习实践项目文件。 注&#xff1a;我笔记实践都是从原始空项目工程文件开始配置的。 有道是 —_—_—_—_— “山无重数周遭碧&#xff0c;花不知名分外娇” “曲…
阅读更多...
行为型设计模式02-模板方法模式

行为型设计模式02-模板方法模式

&#x1f9d1;‍&#x1f4bb;作者&#xff1a;猫十二懿 &#x1f3e1;账号&#xff1a;CSDN 、个人博客 、Github &#x1f38a;公众号&#xff1a;猫十二懿 模板方法模式 1、模板方法模式介绍 模板方法模式是一种行为型设计模式&#xff0c;定义了一个算法的框架&#xff0…
阅读更多...
现代化个人博客系统 ModStartBlog v7.4.0 暗黑模式跟随系统，随机博客获取

现代化个人博客系统 ModStartBlog v7.4.0 暗黑模式跟随系统，随机博客获取

ModStart 是一个基于 Laravel 模块化极速开发框架。模块市场拥有丰富的功能应用&#xff0c;支持后台一键快速安装&#xff0c;让开发者能快的实现业务功能开发。 系统完全开源&#xff0c;基于 Apache 2.0 开源协议。 功能特性 丰富的模块市场&#xff0c;后台一键快速安装 …
阅读更多...
基于GMM的一维时序数据平滑算法

基于GMM的一维时序数据平滑算法

本文将介绍我们使用高斯混合模型(GMM)算法作为一维数据的平滑和去噪算法。 假设我们想要在音频记录中检测一个特定的人的声音&#xff0c;并获得每个声音片段的时间边界。例如&#xff0c;给定一小时的流&#xff0c;管道预测前10分钟是前景(我们感兴趣的人说话)&#xff0c;然…
阅读更多...
OSPF协议知识点

OSPF协议知识点

OSPF 七种状态机 down--- 关闭状态 ---- 一旦启动了 OSPF 协议&#xff0c;则发出 hello 包&#xff0c;并进入下一状态 init---- 初始化状态 ---- 收到的 hello 包中&#xff0c;存在自己的 RID 值&#xff0c;则进入下一状态 2-way---- 双向通讯状态 ----- 邻居关系建立的…
阅读更多...
Linux kernel调试 SPI NORFLASH--W25Q128

Linux kernel调试 SPI NORFLASH--W25Q128

W25Q128介绍 W25Q128 是华邦公司推出的一款 SPI 接口的 NOR Flash 芯片&#xff0c;其存储空间为 128Mbit&#xff0c;相当于 16M 字节。W25Q128 可以支持 SPI 的模式 0 和模式 3&#xff0c;也就是 CPOL0/CPHA0 和CPOL1/CPHA1 这两种模式。      Flash 写入数据时和 EEPR…
阅读更多...
【Linux初阶】基础IO - 文件操作(使用系统接口实现) | vim批量注释代码

【Linux初阶】基础IO - 文件操作(使用系统接口实现) | vim批量注释代码

&#x1f31f;hello&#xff0c;各位读者大大们你们好呀&#x1f31f; &#x1f36d;&#x1f36d;系列专栏&#xff1a;【Linux初阶】 ✒️✒️本篇内容&#xff1a;重新理解文件和文件操作&#xff0c;C语言实现的简单文件操作&#xff0c;文本初始权限&#xff0c;系统接口介…
阅读更多...
【spring源码系列-01】spring底层源码整体概述

【spring源码系列-01】spring底层源码整体概述

JVM系列整体栏目 内容链接地址【一】spring源码整体概述https://blog.csdn.net/zhenghuishengq/article/details/130940885 初识虚拟机与java虚拟机 一&#xff0c;spring源码整体概述1&#xff0c;初步概述2&#xff0c;扩展点机制3&#xff0c;核心方法refresh4&#xff0c;B…
阅读更多...
【wpf】xaml 中的参数复用

【wpf】xaml 中的参数复用

背景 xaml中有几种复用的方式&#xff1a; 有时在xaml中&#xff0c;我们需要复用一些参数&#xff0c;比如 固定的一个值。 有时是固定的一个样式。 资源&#xff0c;sys的引入 有时多个控件都要设置一个高度&#xff0c;我可以引入sys 声明 我就使用这个吧&#xff1a…
阅读更多...
扬帆出海正当时，企业应该做好哪些准备？

扬帆出海正当时，企业应该做好哪些准备？

在跨境出海的时代大潮中&#xff0c;想要拓展海外市场的中国企业&#xff0c;应该事先做好哪些准备&#xff1f; 中国企业出海的新格局 首先来看一组令人振奋的数据。来自中国信通院的数据显示&#xff0c;在2020年的时候&#xff0c;中国数字经济的规模就达到了39.2万亿元人民…
阅读更多...
本地Linux搭建web服务并发布公网访问

本地Linux搭建web服务并发布公网访问

文章目录 前言1. 本地环境服务搭建2. 局域网测试访问3. 内网穿透3.1 ubuntu本地安装cpolar内网穿透3.2 创建隧道3.3 测试公网访问 4. 配置固定二级子域名4.1 保留一个二级子域名4.2 配置二级子域名4.3 测试访问公网固定二级子域名 转载自cpolar极点云的文章&#xff1a;在Ubunt…
阅读更多...
玩转华为云Astro低代码体验季

玩转华为云Astro低代码体验季

目录 Astro轻应用应用场景 零代码应用构建 轻应用构建 行业应用构建 业务大屏构建 使用体验 功能建议 总体评价 Astro轻应用&#xff08;Astro Zero&#xff0c;简称AstroZero&#xff09;是华为云为行业客户、合作伙伴、开发者量身打造的低代码/零代码应用开发平台&#xff0c…
阅读更多...
C++ A lambda function

C++ A lambda function

lambda 函数是 C 中的匿名函数&#xff0c;可以内联定义并用作函数对象。 下面是定义 lambda 函数的一般语法&#xff1a; [capture list] (parameter list) -> return type { function body }lambda 语法的每个部分&#xff1a; - capture list&#xff1a;这是一个可选的…
阅读更多...
R实践——【rgplates】功能函数解析

R实践——【rgplates】功能函数解析

【rgplates】功能函数解析 1. 板块和特征重建2. 构造模型表示2.1 用法2.2 参数2.3 值2.4 示例 3. 实用工具3.1 用法3.2 参数3.3. 值3.4 示例 1. 板块和特征重建 一切与几何形状重建到过去状态有关的东西 reconstruct()&#xff1a;重建地理特征 详见R语言实践——古今地理坐…
阅读更多...
4. WebGPU 存储缓冲区 （WebGPU Storage Buffers）

4. WebGPU 存储缓冲区 （WebGPU Storage Buffers）

这篇文章是关于存储缓冲区的&#xff0c;我们从上一篇文章暂停的地方继续。 存储缓冲区在许多方面类似于统一缓冲区。如果我们所做的只是将 JavaScript 中的 UNIFORM 更改为 STORAGE 并将 WGSL 中的 var 更改为 var<storage, read> &#xff0c;那么上一页中的示例就可以…
阅读更多...
Zabbix“专家坐诊”第193期问答汇总

Zabbix“专家坐诊”第193期问答汇总

问题一 Q&#xff1a;大佬们&#xff0c;怎么才能将zabbix-server接收到的数据全部展示出来呢&#xff1f;目前我的显示数据无法全部显示。 A&#xff1a;这个是用zabbix_sender发送过来的&#xff1f;确认下数据中是否包含空格等&#xff0c;如果有空格使用反斜杠转义或者单…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023