首页 > 其他分享 >后端 API 接口文档 Swagger 使用指南

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

时间：2023-12-23 22:34:16浏览次数：56  
标签：Swagger return 电影 ResultModel API 使用指南 import swagger id

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

转载自：https://zhuanlan.zhihu.com/p/98560871
  • 前言
  • 一：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的作用。实在是开发编程必备良品啊。

来源：Yrion cnblogs.com/wyq178

标签：Swagger,return,电影,ResultModel,API,使用指南,import,swagger,id
From： https://www.cnblogs.com/wanghengbin/p/17923755.html

相关文章

  • Swagger(一) Swagger/Springfox 入门简介
    转载自：https://blog.csdn.net/donglinjob/article/details/108550636 Swagger/Springfox入门简介一、Swagger 简介1前言接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要，但是由于项目周期等原因后端人员经......
  • openai api
    0.介绍chatgpt是一个人工智能模型，该公司提供了可调用的api接口进行使用。1.openai库python下载安装openai库，即可使用官方提供的库文件进行api使用。pipinstallopenai据目前所了解资料，openai认证方式是通过密钥进行验证，密钥生成之后就不会显示第二次，所以需要进行......
  • 京东JDAPI：电商行业的得力助手
    一、引言在当今电商行业中，数据的获取与利用显得尤为重要。作为中国领先的电商平台，京东提供了丰富的API接口，其中JD商品详情API是关键之一，它允许第三方开发者获取京东平台上的商品详情信息。本文将深入探讨京东JD商品详情API在电商行业中的重要性，以及如何通过该API实现实时数据获取。......
  • python脚本打包api flask pyinstaller
    如果你想将Python脚本打包成API，你可以使用Flask框架³。以下是一个简单的步骤：安装Flask。你可以使用pip来安装Flask³：pipinstallFlask创建一个新的Python文件，例如app.py³。在这个文件中，你可以定义你的API接口³。如果你想将Python脚本打包成可执行程序，你可以使用PyInstaller¹。......
  • 使用ApiFox做简单的接口并发压力测试
    前言笔者原计划是学着用jmeter来搞个简单的并发测试，但是...好好好，笔者刚好安装了apifox，计划有变！1.新建测试场景2.编辑测试步骤3.查看测试结果查看请求的详细信息更多详细信息4.数据库验证笔者测试目的主要是想验证该接口在并发压力下是否会存在日志丢失、线程池占......
  • WGCLOUD使用指南 - agent进程停止运行，如何处理
    有时候agent在运行过程中，会莫名其妙的出现进程停止的情况，有可能是人工误操作导致的，也有可能是被系统或程序kill掉，这种情况可以使用agent-backup来避免agent-backup不是必须部署的，只有您出现以上情况时候，再考虑部署agent-backupagent-backup是一个agent的备份程序，主要用来监听agen......
  • 使用代码生成工具快速开发应用-结合后端Web API提供接口和前端页面快速生成，实现通用的
    在前面随笔《在Winform应用中增加通用的业务编码规则生成》，我介绍了基于Winform和WPF的一个通用的业务编码规则的管理功能，本篇随笔介绍基于后端WebAPI接口，实现快速的Vue3+ElementPlus前端界面的开发整合，同样是基于代码生成工具实现快速的前端代码的生成处理。1、通用的业务编码......
  • 自然语言处理：通过API调用各大公司的机器翻译开放平台
    国内大公司做机器翻译做的比较好的有讯飞和百度，这里给出这两个公司机器翻译的开放平台API的介绍：讯飞开放平台：链接：https://www.xfyun.cn/doc/nlp/xftrans_new/API.html#%E6%8E%A5%E5%8F%A3%E8%AF%B4%E6%98%8E百度翻译平台：链接：https://api.fanyi.baidu.com/doc/21......
  • 超好用的API协作管理工具：Apipost
    在当今快速发展的数字化时代，API已成为企业与开发者实现数据互通、应用集成的重要桥梁。然而，随着API数量的不断增加，API开发、调试、测试、文档等工作也变得越来越复杂。为了解决这一痛点，一款名为Apipost的API协同研发工具应运而生。成功案例许多知名的公司和团队都在使用Apipost......
  • 免费！Apipost IDEA插件
    IDEA插件市场中的API调试插件不是收费（FastRequest）就是不好用（apidoc、apidocx等等）今天给大家介绍一款国产的API调试插件：Apipost-Helper，完全免费且好看好用！这款插件由Apipost团队开发的，其官方介绍是：用于IDEA项目快速生成API文档，快速查询接口、接口代码功能，并支持在IDEA中进行API......

赞助商

阅读排行

网站主页关于我们联系我们网站地图

本网站内容转载自其他媒体，侵权联系[admin##ips99.com]。

Copyright © 2020-2023 IPS99 版权所有 IPS99