Swagger Editor 簡介

1. 前言

大家好，今天為大家介紹 Swagger Editor。Swagger Editor 和 Swagger Codegen 不同，Swagger Editor 適用于一切規(guī)模的項目，話不多說，咱們直入正題。

2. 什么是 Swagger Editor ？

什么是 Swagger Editor 呢？在 Swagger 官網(wǎng)中是這么介紹的：

Swagger Editor 是一個開源編輯器，我們可以在這個開源編輯器上設計、描述和記錄我們的 API 信息，通過 Swagger Editor 這個開源編輯器進行配置而生成的 API 是符合 RESTFUL API 規(guī)范的，并且 Swagger Editor 這款開源編輯器支持 Swagger 2.0 版本和 RESTFUL API 3.0 版本。 —官網(wǎng)

注意：這里提到的 OpenAPI 其實就是我們所謂的 RESTFUL API 規(guī)范，關于 RESTFUL API 規(guī)范我們已經(jīng)在 Swagger 簡介這一小節(jié)中做了詳細的介紹，有不清楚的同學可以到該小節(jié)了解，這里不再贅述。

通過上面的介紹，說白了，Swagger Editor 就是一款提供了可以直接設計、描述和記錄項目中所有的接口為 RESTFUL API 文檔的開源編輯器，可以幫助我們提升項目開發(fā)效率。

3. 為什么要使用 Swagger Editor ？

那么我們?yōu)槭裁匆褂?Swagger Editor 呢？

3.1 完善的 RESTFUL API 生成機制

對于任何規(guī)模大小的項目而言，無論是小項目還是大項目，都會涉及到項目接口的開發(fā)，而對于項目接口的管理，最常見的就是根據(jù)項目接口內容撰寫項目接口文檔，但是這種方式有一種顯而易見的弊端。

當項目中接口開發(fā)的需求發(fā)生變化時，根據(jù)項目管理規(guī)范，我們需要首先修改之前撰寫好的相應的接口文檔，由于種種原因，導致我們的修改時機很慢而不能及時支撐該接口的修改交付工作，這就會產生沖突，就會不得已先進行接口的修改，后續(xù)再來修改接口文檔了。

針對上述類似問題，如果我們使用 Swagger Editor 來對接口進行維護，就會大大降低這種問題出現(xiàn)的概率。

Swagger Editor 提供了強大的配置文件類型，例如我們熟知的 yml 配置源文件和少數(shù)的 json 配置源文件，針對這兩種配置文件，Swagger Editor 內置了豐富的 RESTFUL API 屬性，開發(fā)人員可以直接使用這些屬性來描述項目中的接口信息，不需要專門再將接口修改為符合 RESTFUL API 規(guī)范而發(fā)愁了。

3.2 美觀的界面顯示效果

在第一章中，當我們在項目中集成了 Swagger 框架之后，運行項目之后會為我們生成 Swagger-ui 界面，我們都知道這個界面還是相對美觀一些的，我們也可以直接在這個界面上瀏覽接口和其他信息。

Swagger Editor 在配置好之后的生成界面幾乎是和 Swagger-ui 界面是一模一樣的，而且 Swagger Editor 的生成界面允許我們邊修改配置信息邊查看修改結果，可以實時看到我們的修改結果。

這就表明，如果我們項目中的接口需求發(fā)生了變動，我們可以直接在 Swagger Editor 中修改相應的配置信息，并且可以實時看到修改結果，這對開發(fā)人員來說是一個’福音’。

4. 學習基礎

1. 學習 Swagger Editor 這個工具和 Swagger Codegen 一樣，需要大家真實開發(fā)過項目并且對項目進行過簡單的配置，并且使用的是 Java 7 或以上的 JDK 版本。

2. 如果你是一名后端開發(fā)人員，那么相信你在學習 Swagger Editor 時會信手拈來。

5. 小結

Swagger Editor 其實就是一款可以為項目中的接口生成 RESTFUL API 規(guī)范界面的開源工具，其完善的 RESTFUL API 生成機制和美觀的界面顯示效果可以在提升項目接口的維護效率的同時增強接口文檔的交互性，這也是 Swagger Editor 的核心魅力。