运用Swagger编写API文档

最新推荐文章于 2024-07-26 09:36:54 发布
最新推荐文章于 2024-07-26 09:36:54 发布
阅读量2.1k 收藏 10
点赞数
分类专栏： 服务器 前端 文章标签： Swagger
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/weixin_40826349/article/details/86479070
版权

1 运用Swagger编写API文档

1.1 Swagger

1.1.1什么是Swagger

​ 随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。
​ 前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。

1.1.2 SwaggerEditor安装与启动

（1）下载 https://github.com/swagger-api/swagger-editor/releases/download/v2.10.4/swagger-editor.zip。我在资源中已经提供。

（2）解压swagger-editor,

（3）全局安装http-server(http-server是一个简单的零配置命令行http服务器)

npm install -g http-server

（4）启动swagger-editor

http-server swagger-editor

（5）浏览器打开： http://localhost:8080

在这里插入图片描述

1.1.3 语法规则

（1）固定字段

字段名类型描述
swaggerstring必需的。使用指定的规范版本。
infoInfo Object必需的。提供元数据API。
hoststring主机名或ip服务API。
basePathstringAPI的基本路径
schemes[string]API的传输协议。 值必须从列表中:“http”,“https”,“ws”,“wss”。
consumes[string]一个MIME类型的api可以使用列表。值必须是所描述的Mime类型。
produces[string]MIME类型的api可以产生的列表。 值必须是所描述的Mime类型。
paths路径对象必需的。可用的路径和操作的API。
definitions定义对象一个对象数据类型生产和使用操作。
parameters参数定义对象一个对象来保存参数,可以使用在操作。 这个属性不为所有操作定义全局参数。
responses反应定义对象一个对象响应,可以跨操作使用。 这个属性不为所有操作定义全球响应。
externalDocs外部文档对象额外的外部文档。
summarystring什么操作的一个简短的总结。 最大swagger-ui可读性,这一领域应小于120个字符。
descriptionstring详细解释操作的行为。GFM语法可用于富文本表示。
operationIdstring独特的字符串用于识别操作。 id必须是唯一的在所有业务中所描述的API。 工具和库可以使用operationId来唯一地标识一个操作,因此,建议遵循通用的编程的命名约定。
deprecatedboolean声明该操作被弃用。 使用声明的操作应该没有。 默认值是false。

（2）字段类型与格式定义

普通的名字typeformat说明
integerintegerint32签署了32位
longintegerint64签署了64位
floatnumberfloat
doublenumberdouble
stringstring
bytestringbytebase64编码的字符
binarystringbinary任何的八位字节序列
booleanboolean
datestringdate所定义的full-date- - - - - -RFC3339
dateTimestringdate-time所定义的date-time- - - - - -RFC3339
passwordstringpassword用来提示用户界面输入需要模糊。

1.2 基础模块-城市API文档

1.2.1 新增城市

编写新增城市的API , post提交城市实体

URL： /city

Method: post

编写后的文档内容如下：

在这里插入图片描述

代码如下：

swagger: '2.0'
info:
  version: "1.0.0"
  title: 基础模块-城市API
basePath: /base
host: api.tensquare.com
paths:
  /city:
    post:
      summary: 新增城市
      parameters:
        - name: "body"
          in: "body"
          description: 城市实体类
          required: true
          schema:
            $ref: '#/definitions/City'
      responses:
        200:
          description: 成功
          schema:
            $ref: '#/definitions/ApiResponse'
definitions:
  City: 
    type: object
    properties: 
      id: 
        type: string
        description: "ID"
      name:
        type: string
        description: "名称"
      ishot:
        type: string
        description: 是否热门
  ApiResponse: 
    type: object
    properties: 
      flag: 
        type: boolean
        description: 是否成功
      code:
        type: integer
        format: int32
        description: 返回码
      message:
        type: string
        description: 返回信息

编辑后可以在右侧窗口看到显示的效果

1.2.2 修改城市

URL： /city/{cityId}

Method: put

编写后的文档内容如下：

在这里插入图片描述

代码如下：

  /city/{cityId}:
    put:
      summary: 修改城市
      parameters:
        - name: cityId
          in: path
          description: 城市ID
          required: true
          type: string
        - name: body
          in: body
          description: 城市
          schema:
            $ref: '#/definitions/City'
      responses:
        200:
          description: 成功响应
          schema:
            $ref: '#/definitions/ApiResponse'

1.2.3 删除城市

删除城市地址为/city/{cityId} ，与修改城市的地址相同，区别在于使用delete方法提交请求

在这里插入图片描述

代码如下： （/city/{cityId} 下增加delete）

    delete:
      summary: 根据ID删除
      description: 返回是否成功
      parameters:
        - name: cityId
          in: path
          description: 城市ID
          required: true
          type: string
      responses:
        '200':
          description: 成功
          schema:
            $ref: '#/definitions/ApiResponse'

1.2.4 根据ID查询城市

URL: /city/{cityId}

Method: get

返回的内容结构为： {flag:true,code:20000, message:“查询成功”,data: {…} }

data属性返回的是city的实体类型

在这里插入图片描述

代码实现如下：

（1）在definitions下定义城市对象的响应对象

  ApiCityResponse:
    type: "object"
    properties:
      code:
        type: "integer"
        format: "int32"
      flag:
        type: "boolean"
      message:
        type: "string"
      data:
        $ref: '#/definitions/City'

（2）/city/{cityId} 下新增get方法API

    get:
      summary: 根据ID查询
      description: 返回一个城市
      parameters:
        - name: cityId
          in: path
          description: 城市ID
          required: true
          type: string
      responses:
        '200':
          description: 操作成功
          schema:
            $ref: '#/definitions/ApiCityResponse'

1.2.5 城市列表

URL: /city

Method: get

返回的内容结构为： {flag:true,code:20000, message:“查询成功”,data:[{…},{…},{…}] }

data属性返回的是city的实体数组

在这里插入图片描述

实现步骤如下：

（1）在definitions下定义城市列表对象以及相应对象

  CityList:
    type: "array"
    items: 
      $ref: '#/definitions/City'
  ApiCityListResponse:
    type: "object"
    properties:
      code:
        type: "integer"
        format: "int32"
      flag:
        type: "boolean"
      message:
        type: "string"
      data:
        $ref: '#/definitions/CityList'

（2）在/city增加get

    get:
      summary: "城市全部列表"
      description: "返回城市全部列表"
      responses:
        200:
          description: "成功查询到数据"
          schema: 
            $ref: '#/definitions/ApiCityListResponse'

1.2.6 根据条件查询城市列表

实现API效果如下:

在这里插入图片描述

代码如下：

  /city/search:
    post:
      summary: 城市列表(条件查询)
      parameters:
        - name: body
          in: body
          description: 查询条件
          required: true
          schema:
            $ref: "#/definitions/City"
      responses:
        200:
          description: 查询成功
          schema:
            $ref: '#/definitions/ApiCityListResponse'

1.2.7 城市分页列表

实现API效果如下：

在这里插入图片描述

实现如下：

（1）在definitions下定义城市分页列表响应对象

  ApiCityPageResponse:
    type: "object"
    properties:
      code:
        type: "integer"
        format: "int32"
      flag:
        type: "boolean"
      message:
        type: "string"
      data:
        properties:
          total:
            type: "integer"
            format: "int32"
          rows:
            $ref: '#/definitions/CityList'

（2）新增节点

  /city/search/{page}/{size}:
    post:
      summary: 城市分页列表
      parameters:
        - name: page
          in: path
          description: 页码
          required: true
          type: integer
          format: int32
        - name: size
          in: path
          description: 页大小
          required: true
          type: integer
          format: int32
        - name: body
          in: body
          description: 查询条件
          required: true
          schema:
            $ref: "#/definitions/City"
      responses:
        200:
          description: 查询成功
          schema:
            $ref: '#/definitions/ApiCityPageResponse'

1.3 批量生成API文档

我们使用《黑马程序员代码生成器》自动生成所有表的yml文档

自动生成的文档中类型均为string ，我们这里需要再对类型进行修改即可。

步骤：

（1）执行建表脚本

（2）使用《黑马程序员代码生成器》生成脚本

1.4 其它模块API

请学员参见本章的扩展文档来实现部分功能。

1.5 SwaggerUI

SwaggerUI是用来展示Swagger文档的界面，以下为安装步骤

（1）在本地安装nginx

（2）下载SwaggerUI源码 https://swagger.io/download-swagger-ui/

（3）解压，将dist文件夹下的全部文件拷贝至 nginx的html目录

（4）启动nginx

（5）浏览器打开页面 http://localhost即可看到文档页面

在这里插入图片描述

（6）我们将编写好的yml文件也拷贝至nginx的html目录，这样我们就可以加载我们的swagger文档了

在这里插入图片描述

仲尼叔叔
关注
专栏目录
使用Swagger进行API文档管理详解
fudaihb的博客
07-12 749
在现代软件开发中，API（应用程序接口）是前后端通信的重要桥梁。随着项目的规模和复杂度增加，管理API文档变得愈发重要。Swagger是一个开源工具，可以帮助开发者自动生成、维护和分享API文档。本文将详细介绍Swagger的使用方法，帮助你在项目中更好地管理API文档。
swagger文档编写
01-31
API自动编写文档的工具swagger，API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。
swagger生成api编写指南
最新发布
wangjunlei666的博客
07-26 368
指定调用接口的协议，必须是:“http”, “https”, “ws”, “wss”．默认是http.-表示是个数组元素，即schemes接受一个数组参数。#Swagger会提供测试用例，host指定测试时的主机名，如果没有指定就是当前主机,可以指定端口．。#定义的api的前缀，必须已/开头,测试用例的主机则为:host＋bashPath。swagger在线官方编辑器：https://editor.swagger.io/swagger生成api的接口文档yaml版本。描述API接口信息的元数据。
swagger编写api_使用swagger在Node JS中自动编写API文档
weixin_26735933的博客
09-07 932
swagger编写apiOriginal article in Portuguese Brazil: (Click here) 巴西葡萄牙语原文：( 点击这里 ) For those who develop APIs in Node.js, whether at a professional level or not, you know that keeping the project docu...
Swagger编写API文档的YAML示例
10-11
通过Swagger Editor,使用yaml编写的API接口文档，导入到Swagger Editor即可看到效果．
swagger编写规范
xxoo00xx00的博客
08-16 1万+
swagger 学习笔记环境: 1,jdk1.8 2,idea 3,spring-boot-starter-parent版本1.5.6.RELEASE 4,springfox-swagger2 And springfox-swagger-ui 版本2.2.2。如果修改版本号持续报错，尝试删除m2里面swagger的所有jar包， 1 Swagger环境搭建 新建一个工程，file->new-
Swagger编写API文档的YAML
心暖未晴
03-28 7389
#必要字段！Swagger规范版本，必须填2.0，否则该YAML将不能用于Swagger其他组件swagger: '2.0'#必要字段！描述API接口信息的元数据info: #接口标题 title: swagger说明文档　 #接口文档的描述 description: 学习Swagger #版本号 version: 1.0.0#Swagger会提供测试用例，host指定测试时的主机名，...
swagger工具编写接口文档
qq_60555957的博客
11-03 1140
swagger工具编写接口文档
运用swagger编写api文档
smile radiantly
12-01 325
一.什么是swagger 随着互联网技术的发展,前后端技术在各自的道路上越走越远,他们之间的唯一联系变成了api接口,api接口文档编程了前后端人员的纽带,而swagger就是书写api文档的一款框架. 官网: https://swagger.io/ 二.SwaggerEditor的安装与启动 下载 swagger-editor.zip 解压swagger-editor 全局安装http-ser...
手动编写Swagger文档与部署指南
lbw520的博客
07-18 1766
Swagger介绍 在Web开发中，后端开发者在完成接口开发后，需要给前端相应的接口使用说明，所以一般会写一份API文档。一般来说，有两种方式提供API接口文档，一种是利用插件在代码中自动生成，另一种是手工编写API文档。 Swagger就是为API文档设计而生的，其中包含一整套相关工具，既支持利用插件在代码中进行注解从而自动生成文档，也支持手工编写文档。两种方式各有优缺点： 自动生成：省时，方...
swagger-api-docs:swagger-api-docs
05-04
api-doc-swagger 昂扬的API文档 与HTTP服务器一起运行 $ brew安装节点 安装http服务器 $ npm安装http-server -g 运行应用程序 $ http-服务器。 快速运行 $ npm我 $节点server.js 与DOCKER图像一起运行 $ docker build -f Dockerfile -t docker-image-name。 $ docker运行它-d -p主机端口：DOCKER端口docker-image-name 例子 $ docker build -f Dockerfile -t api-doc。 $ docker run -p 8080：8080 api-doc $ docker ps -a $ docker stop容器ID 列出所有图像 $泊坞窗图片 列出所有过程 $ docker ps -a 删除所有的容器 $泊坞
Swagger Editor编写
tiki的博客
06-22 1676
Swagger Editor编写一、Swagger Editor编辑器1.在线编写2.IDEA安装插件3.两种方式优缺点二、语法规则1.字段类型与格式定义三、示例说明1.编写get-yaml示例1.1可视化界面2.编写post-yaml示例2.1可视化界面 一、Swagger Editor编辑器 1.在线编写 https://editor.swagger.io/ 其是官方提供的编写swagger yaml文件的在线编辑器，且可以实时看见编写的yaml文件的可视化页面 2.IDEA安装插件 在插件库中搜索sw
swagger：安装、文档编写、swaggerUI
Sakuraaaaaaa的博客
08-24 426
swagger： 概述， 安装， 编写城市api文档， swaggerUI。
Swagger API 文档 | SpringDoc 常用配置
甘蓝的专栏
04-12 751
介绍SpringDoc常用配置。
swagger生成RESTful API的doc文档
小儍鈲的专栏
12-05 3792
今天看见同事使用swagger的注解为RESTful接口生成API文档，感觉特别高级，对接口的描述看着也非常清晰，比自己写的接口文档规范，于是就百度了swagger，于是就找到了下面要转载的文章，把swagger的用法描述的还是比较清新的： 尊重原创，只贴链接：https://www.cnblogs.com/woshimrf/p/5863318.html
2022-01-24 五.Swagger API文档
不爱吃奶昔（zsl0）的博客
01-24 1082
Swagger-API文档Swagger配置导包编写配置类配置类资源类yaml注解@Api@ApiOperation@ApiModel@ApiModelProperty@ApiImplicitParams@ApiResponses@ApiIgnoreswagger-ui3以下版本3及以上版本参考文章 Swagger 配置 导包 3.0.0以下版本maven导入依赖： <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagg
swagger
weixin_42807940的博客
10-18 231
#必要字段！Swagger规范版本，必须填2.0，否则该YAML将不能用于Swagger其他组件 swagger: ‘2.0’ #必要字段！描述API接口信息的元数据 info: #接口标题 title: swagger说明文档　 #接口文档的描述 description: 学习Swagger #版本号 version: 1.0.0 #Swagger会提供测试用例，host指定测试时的主机名，如果...
Swagger-API文档生成框架的基本使用
热门推荐
了无牵挂者忘生，心有所爱者忘死
04-19 5万+
　　使用工具、框架的目的就是为了开发过程简洁方便或者是达到更强大的功能效果。在目前互联网开发发展的趋势下，由于技术更加深度化、细化，前后端分离开发成为必不可少的一个环节，而后端和前端开发人员之间唯一的桥梁便是API文档，也就是接口文档。 　　平时开发中大部分接口开发都会由开发者或者特定人员手写接口文档。而文档也会随着项目迭代不停更新，由此需要不停有人员维护API文档的内容。消耗时间同时...
使用Swagger编写API文档指南
"本文档是关于使用Swagger编写API文档的指南，旨在帮助读者理解Swagger的基本概念，学习如何根据OpenAPI规范创建API文档，并了解Swagger在API开发中的重要性和应用。" Swagger是一个流行的API框架，其核心是提供了...
评论 1
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值