Swagger基礎總結

2021-09-16 12:03:17 字數 2636 閱讀 8316

the best apis are built with swagger tools

swagger分為四部分:

1.openapi規範的版本號

通過乙個 swagger 屬性來宣告openapi規範的版本。

swagger: 「2.0」

2.api描述資訊:

文件相關資訊

info:

version:1.0.0

title:****** api

description:a ****** api to learn how to write openapi specification

3.api的url

作為web api,乙個很重要的資訊就是用來給消費者使用的 根url ,可以用協議

(http或者https)、主機名、根路徑來描述:

意義:4.api的操作

4.1新增乙個 路徑

paths:

/persons:

4.2在路徑中新增乙個http方法

比如需要展示一組使用者資訊,我們可以在 /persons 路徑中新增 get 方法,同時

還可以填寫一些簡單的描述資訊(summary)或者說明該方法的一段長篇大論

(description)。

get:

summary: gets some persons

description: returns a list containing all persons.

4.3定義 響應 (response)型別

對於每個方法(或操作),我們都可以在 響應 (responses)中新增任意的http狀

態碼(比如200 ok 或者 404 not found等)。這個例子中我們新增上 200 的響

應:responses:

200:

description: a list of person

4.4定義響應內容

get /persons這個介面返回一組使用者資訊,我們通過響應訊息中的 模

式 (schema)屬性來描述清楚具體的返回內容。

一組使用者資訊就是乙個使用者資訊物件的 陣列 (array),每乙個陣列元素則是乙個

使用者資訊 物件 (object),該物件包含三個string型別的屬性: 姓氏 、 名

字 、 使用者名稱 ,其中 使用者名稱 必須提供(required)。

schema:

type:array

items:

required:

-username

properties:

firstname:

type:string

lastname:

type:string

username:

type:string

4.5定義 請求引數 (query parameters)

parameters:

in: query

description: number of persons returned

type: integer

in: query

description: page number

type: integer

4.5.1在get方法中增加請求引數

parameters:

4.5.2新增分頁引數

在引數列表中,我們新增兩個名字(name)分別叫

做 pagesize 和 pagenumber 的整型(integer)引數,並作簡單描述:

in: query

description: number of persons returned

type: integer

in: query

description: page number

type: integer

Swagger基礎學習

api框架 restful文件自動生成工具,api文件與定義的同步更新 使用兩個庫 io.springfoxgroupid springfox swagger uiartifactid 2.10.5version dependency io.springfoxgroupid springfox sw...

Swagger基礎配置

前後端分離開發模式中,api文件是最好的溝通方式。swagger 是乙個規範和完整的框架,用於生成 描述 呼叫和視覺化 restful 風格的 web 服務。1.及時性 介面變更後,能夠及時準確地通知相關前後端開發人員 2.規範性 並且保證介面的規範性,如介面的位址,請求方式,引數及響應格式和錯誤資...

Swagger總結 小滿的複習計畫

io.springfoxgroupid springfox swagger2artifactid dependency import com.google.common.base.predicates import org.springframework.context.annotation.bea...