2. 程式人生 > >Swagger編寫API文件的YAML

Swagger編寫API文件的YAML

阿新 • • 發佈：2019-01-25
#必要欄位！Swagger規範版本，必須填2.0，否則該YAML將不能用於Swagger其他元件swagger: '2.0'#必要欄位！描述API介面資訊的元資料info: #介面標題 title: swagger說明文件　 #介面文件的描述 description: 學習Swagger #版本號 version: 1.0.0#Swagger會提供測試用例，host指定測試時的主機名，如果沒有指定就是當前主機,可以指定埠．host: 127.0.0.1#定義的api的字首，必須已/開頭,測試用例的主機則為:host＋bashPathbasePath: /api#指定呼叫介面的協議，必須是:"http"
, "https", "ws", "wss"．預設是http.-表示是個陣列元素，即schemes接受一個數組引數schemes: - http - https#對應與http協議頭request的Accept，呼叫者可接受型別,預設是*/*,定義的型別必須是http協議定義的 Mime Types,RestfulAPI一般定義成application/json#這兩個是對所有介面的全域性設定，在細化的介面中是還可以對應這兩個屬性來覆蓋全域性屬性produces: - application/json#必要欄位!定義可有可操作的APIpaths: /users: #必要欄位!定義HTTP操作方法，必須是http協議定義的方法
get: #介面概要 summary: 查詢所有使用者資訊 #介面描述 description: 查詢出所有使用者的所有資訊，使用者名稱，別名 #標籤，方便快速過濾出User相關的介面 tags: - User #返回值描述，必要自動 responses: #返回的http狀態碼 200: description: 所有使用者資訊或者使用者的集合資訊 #描述返回值 schema: #返回值格式，可選的有array,integer,string,boolean
type: array #針對array,每個條目的格式,type定義為array．必要填寫items items: #引用在definitions下定義的Users $ref: '#/definitions/User' #執行出錯的處理 default: description: 操作異常,執行失敗.返回資訊描述錯誤詳情 schema: #值型別 type: object #定義屬性 properties: #屬性名 message: #型別 type: string #即對於同一個url定義兩個不同的方法，表示兩個介面 post: description: 註冊一個使用者 #請求引數 parameters: #引數key - name: username #傳遞方法，formData表示表單傳輸，還有query表示url拼接傳輸，path表示作為url的一部分 #body表示http頭承載引數(body只能有一個,有body不能在有其他的) in: formData #引數描述 description: 使用者名稱，不能使用已經被註冊過的 #引數是否必要，預設false required: true #引數型別，可選的包括array,integer,boolean,string.使用array必須使用items type: string - name: password in: formData description: 使用者登陸密碼，加密傳輸，加密儲存 required: true type: string - name: alias in: formData type: string description: 使用者別名 #非必要欄位 required: false responses: #返回的http狀態碼 200: description: 通過返回值來標示執行結果　返回true表示執行成功 schema: #值型別 type: object #定義屬性 properties: #屬性名 status: #型別 type: boolean #描述 description: 是否成功 #執行出錯的處理 default: description: 操作異常,執行失敗.返回資訊描述錯誤詳情 schema: #值型別 type: object #定義屬性 properties: #屬性名 message: #型別 type: string /users/{id}: #{id}表示id為請求引數，例如/users/1,/users/2都是對該API的請求，此時id即為１和2 get: summary: 根據使用者名稱id查詢該使用者的所有資訊 description: 查詢出某個使用者的所有資訊，使用者名稱，別名等 tags: - User parameters: #上面介面中定義了{id}，則引數列表中必須包含引數id,並且請求型別為path - name: id in: path description: 要查詢的使用者的使用者名稱,它是唯一標識 required: true type: string responses: 200: description: 所有使用者資訊或者使用者的集合資訊 schema: $ref: '#/definitions/User' default: description: 操作異常,執行失敗.返回資訊描述錯誤詳情 schema: #值型別 type: object #定義屬性 properties: #屬性名 message: #型別 type: string #http定義的delete方法,刪除一個資源 delete: summary: 刪除使用者 description: 刪除某個使用者的資訊，被刪除的使用者將無法登陸 parameters: - name: id in: path type: string required: true description: 使用者的唯一標示符 tags: - User responses: 200: description: 通過返回值來標示執行結果　返回true表示執行成功 schema: #值型別 type: object #定義屬性 properties: #屬性名 status: #型別 type: boolean #描述 description: 是否成功 default: description: 操作異常,執行失敗.返回資訊描述錯誤詳情 schema: #值型別 type: object #定義屬性 properties: #屬性名 message: #型別 type: string #描述錯誤資訊 #http定義的patch方法，表示修改一個資源 patch: summary: 使用者資訊修改 description: 修改使用者資訊(使用者名稱別名) parameters: - name: id in: path description: 使用者名稱,要修改的資料的唯一識別符號 required: true type: string - name: alias in: formData description: 新的使用者別名 required: true type: string tags: - User responses: 200: description: 通過返回值來標示執行結果　返回true表示執行成功 schema: #值型別 type: object #定義屬性 properties: #屬性名 status: #型別 type: boolean #描述 description: 是否成功 default: description: 操作異常,執行失敗.返回資訊描述錯誤詳情 schema: #值型別 type: object #定義屬性 properties: #屬性名 message: #型別 type: string #描述錯誤資訊definitions: User: #值型別 type: object #定義屬性 properties: #屬性名 id: #型別 type: string #描述 description: 使用者的唯一id username: type: string description: 使用者名稱 alias: type: string description: 別名

相關推薦

Swagger編寫API文件的YAML中文示例

#必要欄位！Swagger規範版本，必須填2.0，否則該YAML將不能用於Swagger其他元件 swagger: '2.0' #必要欄位！描述API介面資訊的元資料 info: #介面標題 title: swagger說明文件　 #介面文件的描述

Swagger編寫API文件的YAML

#必要欄位！Swagger規範版本，必須填2.0，否則該YAML將不能用於Swagger其他元件swagger: '2.0'#必要欄位！描述API介面資訊的元資料info: #介面標題 title:

Laravel（PHP）使用Swagger生成API文件不完全指南 - 基本概念和環境搭建 - 簡書

在PHPer中，很多人聽說過Swagger，部分人知道Swagger是用來做API文件的，然而只有少數人真正知道怎麼正確使用Swagger，因為PHP界和Swagger相關的資料實在是太少了。所以鄙人斗膽一試，希望能以本文幫助到大家瞭解Swagger，從此告別成天用Word、Markdown折騰API文件的日

Spring boot 整合 swagger生成api文件（轉換成markdown格式）

spring boot 整合 swagger 步驟 1. 匯入jar包 2. 新增配置類 3. 新增介面類 3. 啟動伺服器 4. 訪問UI頁面,可線上測試介面 5. 匯出swagger原始檔 6. 轉換成markdown格式檔案 1，匯入jar包 gradl

Spring MVC中使用Swagger生成API文件和完整專案示例Demo，swagger

轉載自：http://www.360doc.com/content/17/0914/17/16915_687184334.shtml    實際專案中非常需要寫文件，提高Java服務端和Web前端以及移動端的對接效率。   聽說Swagger這

SpringBoot中整合swagger形成API文件

SpringBoot中整合swagger形成API文件 環境版本 開始使用 1.新增依賴 2.新增Swagger2配置類 3.在Controller中使用 4.訪問 環境版本 springboo

Swagger生成API文件

一、swagger介紹 使用springMVC整合swagger-ui生成 Restful風格的API文件，可以省略手動編寫介面文件的過程，也解決了介面變化需要維護介面文件的過程。 swagger-ui還可以測試spring restful風格的介面功能。 二、Swag

Web Api 2.0中使用Swagger生成Api文件的2個小Tips

當Web Api 2.0使用OAuth2授權時，如何在Swagger中新增Authorization請求頭？ Swagger說明文件支援手動呼叫Api, 但是當Api使用OAuth2授權時，由於沒有地方可以輸入授權Token, 導致響應結果一直是401沒有授權。

Spring MVC中使用Swagger生成API文件和完整專案示例Demo，swagger-server-api

package cn.fansunion.swagger.serverapi.controller; import org.springframework.http.MediaType; import org.springframework.stereotype.Controller; import org

使用springfox-staticdocs生成swagger離線api文件附帶原始碼

使用springfox-staticdocs生成swagger離線api 因為最近公司部分專案使用swagger來管理線上介面，但在某些場景下需要提供離線的api文件。因此在網上參考了一些部落格以後寫了一個小專案，只需要配置對應的url，既可生成離線的a

【WebAPI No.4】Swagger實現API文件功能

介紹： Swagger也稱為Open API，Swagger從API文件中手動完成工作，並提供一系列用於生成，視覺化和維護API文件的解決方案。簡單的說就是一款讓你更好的書寫API文件的框架。 我們為什麼選擇swagger，現在的網站開發結果越來越注重前後端的分離，比如以前的webFrom到現在的mvc模

用sphinx_doc編寫API文件

一.以下均在mac環境下，Linux系統中的操作： 1. 配置Python環境    $ python --version Python 2.7.6 2.安裝sphinx sudo easy_install sphinx 可能因為不匹配因此用這個命令無法下載相應的

如何使用 Grape-Swagger 生成 API 文件

在Rails 專案中使用 Grape 來開發 API, 想嘗試一下通過 swagger 來自動生成 API 文件，至於為什麼要選 swagger 也沒有特別的理由, 在 Ruby China 看過幾篇分享。然後開始 Google 官方文件和一些列子，中間也碰到一些坑，此文主要是總結下配置 swagger 的

基於.NetCore3.1搭建專案系列 —— 使用Swagger做Api文件 (上篇)

前言   為什麼在開發中，介面文件越來越成為前後端開發人員溝通的樞紐呢？   隨著業務的發張，專案越來越多，而對於支撐整個專案架構體系而言，我們對系統業務的水平拆分，垂直分層，讓業務系統更加清晰，從而產生一系統平臺和系統，並使用介面進行資料互動。因此可見，業務的不斷髮展，介面不斷增多，很

基於.NetCore3.1搭建專案系列 —— 使用Swagger做Api文件 (下篇)

前言             回顧上一篇文章《使用Swagger做Api文件 》，文中介紹了在.net core 3.1中，利用Swagger輕量級框架，如何引入程式包，配置服務，註冊中介軟體，一步一步的實現，最終實現生產自動生產API介面

swagger2 離線文件 文件中心搭建 json swagger 自動生成api文件

最近找了一個自動生成api文件的工具swagger，相對swaggerEdit就不說了。個人比較懶，還是自動生成來的便捷，尤其是老專案，新專案在初期可能會維護，但是到了後期就很難保證了。所以，那些需要一些特殊配置說明的文件工具就不提了。 這篇文章主要是在swagger2 swagger UI的基

基於swagger進行介面文件的編寫 Maven + SpringMVC專案整合Swagger

0. 前言 近期忙於和各個銀行的代收介面聯調，根據遇到的問題，對之前編寫的介面進行了修改，需求收集和設計介面時想到了方方面面，生產環境下還是會遇到意想不到的問題，好在基本的執行邏輯已確定，因此只是對介面進行了一些微調，但是收錢無小事，之前在程式碼編寫時對引數進行了很多的校驗，程式碼修改之後一個引數的對不上都

SpringBoot中使用Swagger生成RestFul規範API文件

j簡單介紹Swagger的作用: Swagger是為了描述一套標準的而且是和語言無關的REST API的規範。對於外部呼叫者來說，只需通過Swagger文件即可清楚Server端提供的服務，而不需去閱讀原始碼或介面文件說明。 官方網站為：http://swagger.io 中文網站：http

SpringBoot 使用 swagger 實現Rest Api 文件化

swagger 允許使用者在一個html5 web 頁面中，對API 進行文件化和互動 優點： 功能豐富 ：支援多種註解，自動生成介面文件介面，支援在介面測試API介面功能； 及時更新 ：開發過程中花一點寫註釋的時間，就可以及時的更新API文件，省心省力； 整合簡單 ：通過新增pom依賴

[Swagger]swagger構建你的api文件

Swagger能成為最受歡迎的REST APIs文件生成工具之一，有以下幾個原因： Swagger 可以生成一個具有互動性的API控制檯，開發者可以用來快速學習和嘗試API。 Swagger 可以生成客戶端SDK程式碼用於各種不同的平臺上的實現。 Swagger 檔案可以在許多不同的