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...