Swagger注释@API详细说明

前言：
相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实一个好接口文档很重要，对项目开发起着很重要的作用。正好有这样一个开源API文档生成的项目，完美解决了接口文档的问题，下面我们就简单的了解一下。

Swagger介绍

swagger是当前最好用的Restful API文档生成的开源项目。
通过这套规范，你只需要按照他的规范去定义接口相关的信息。再通过Swagger衍生出来一系列项目和工具，就可以做到生成格式的接口文档。

相关注解说明

作用范围	API	使用位置
对象属性	@ApiModelProperty	用在参数对象的字段上
协议集描述	@Api	用在Controller类上
协议描述	@ApiOperation	用在controller方法上
Response集	@ApiResponses	用在controller方法上
Response	@ApiResponse	用在@ApiResponses里面
非对象参数集	@ApilmplicitParams	用在controller方法上
非对象参数描述	@ApilmplicitParam	用在@ApilmplicitParams的方法里边
描述返回对象的意义	@ApiModel	用在返回对象类上

@API
tags：表示说明，
value: 字段说明，
description：注释说明这个类

@Api(tags = "PmsBrandController", description = "商品品牌管理")
@Controller
@RequestMapping("/brand")
public class PmsBrandController {}

@ApiOperation
value: 字段说明
notes: 注释说明
httpMethod: 说明这个方法被请求的方式
response: 方法的返回值的类型

    @ApiOperation("获取所有品牌列表")@RequestMapping(value = "listAll", method = RequestMethod.GET)@ResponseBody@PreAuthorize("hasAuthority('pms:brand:read')")public CommonResult<List<PmsBrand>> getBrandList() {return CommonResult.success(brandService.listAllBrand());}

@ApiResponse
code: 响应的HTTP状态码
message: 响应的信息内容
@ApiModelProperty
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏

/*** 获取学生编号* @return 学生编号*/@ApiModelProperty(value="学生编号",example="058",required=true)public String getCode() {return code;}

Swagger注释@API详细说明相关推荐

swagger注释API详细说明
API详细说明注释汇总作用范围 API 使用位置对象属性 @ApiModelProperty 用在出入参数对象的字段上协议集描述 @Api 用于controller类上协议描述 @ApiOp ...
ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了
引言在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必是件很痛苦的事情吧,但文档又必须写,而且文档的格式如果没有具体要求的话,最终完成的文档则完全取决于开发者 ...
【转】ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了
原文链接:https://www.cnblogs.com/yilezhu/p/9241261.html 引言在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必 ...
浅析如何在Nancy中使用Swagger生成API文档
原文:浅析如何在Nancy中使用Swagger生成API文档前言上一篇博客介绍了使用Nancy框架内部的方法来创建了一个简单到不能再简单的Document.但是还有许许多多的不足. 为了能稍微完善 ...
ABP学习实践(五)--引入Swagger对API接口进行管理
以目前流行的前后端分离模式来看,ABP框架更适用于后端开发,而对API接口的管理就成了一项必不可少的功能. 1.安装Swashbuckle.AspNetCore 使用Nuget管理器在分布式服务层和展 ...
SpringBoot整合Swagger测试api构建
@Author:SimpleWu 什么是Swagger? Swagger是什么:THE WORLD'S MOST POPULAR API TOOLING 根据官网的介绍: Swagger Inspec ...
Spring MVC中使用Swagger生成API文档和完整项目示例Demo，swagger-server-api（二十）
一:Swagger介绍 Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目实现了与SpingMVC框架的无缝集成功能,方便生成spring r ...
基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档(上篇)
前言为什么在开发中,接口文档越来越成为前后端开发人员沟通的枢纽呢? 随着业务的发张,项目越来越多,而对于支撑整个项目架构体系而言,我们对系统业务的水平拆分,垂直分层,让业务系统更加清晰,从而产生一系 ...
基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档 (下篇)
前言回顾上一篇文章<使用Swagger做Api文档 >,文中介绍了在.net core 3.1中,利用Swagger轻量级框架,如何引入程序包,配置服务,注册中间件,一步一步的实现,最终 ...

Swagger注释@API详细说明

Swagger介绍

相关注解说明

Swagger注释@API详细说明相关推荐

最新文章

热门文章