java后端Swagger接口

最新推荐文章于 2025-11-11 07:15:00 发布

原创最新推荐文章于 2025-11-11 07:15:00 发布 · 1.8k 阅读

1 ·

CC 4.0 BY-SA版权

文章标签：

#接口 #java #restful #http

Java框架同时被 2 个专栏收录

4 篇文章

订阅专栏

接口文档

1 篇文章

订阅专栏

本文详细介绍如何使用Swagger生成API文档，包括在Java项目中如何通过注解定义接口文档，以及如何描述参数及其作用。

Swagger

随着现在越来越多的项目开始前后端分离，接口开发文档就变的尤为重要，一般开发中常用的文档有swagger、Yapi等，本章项目先介绍swagger。

1.java层-控制层引入，注解，写法

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

@Api(tags = "XX接口")   --中文名字
@RestController
@RequestMapping("/xx/xxx")   --请求的公共路径

@ApiOperation("根据ID查询详情")  --具体接口名字
@GetMapping("/xxxx/{id}") --调用路径
1.1--单个参数
@ApiImplicitParam(name = "id", value = "xxID", required = true, dataType = "int", paramType = "path")
1.2--多个参数
@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "ID", required = false, dataType = "int"),
        @ApiImplicitParam(name = "sxx", value = "值2", required = false, dataType = "double"),
        @ApiImplicitParam(name = "sxxx", value = "值3", required = false, dataType = "String")})

详解

name：参数名；value：参数的汉字说明、解释；required：参数是否必须传；paramType：参数放在哪个地方； header --> 请求参数的获取：@RequestHeader；query --> 请求参数的获取：@RequestParam； path（用于restful接口）--> 请求参数的获取：@PathVariable；dataType：参数类型，默认String，其它值dataType="Integer"；defaultValue：参数的默认值

2.完成展示效果