Swagger Editor 簡(jiǎn)介

1. 前言

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

2. 什么是 Swagger Editor ？

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

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

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

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

3. 為什么要使用 Swagger Editor ？

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

3.1 完善的 RESTFUL API 生成機(jī)制

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

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

針對(duì)上述類似問(wèn)題，如果我們使用 Swagger Editor 來(lái)對(duì)接口進(jìn)行維護(hù)，就會(huì)大大降低這種問(wèn)題出現(xiàn)的概率。

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

3.2 美觀的界面顯示效果

在第一章中，當(dāng)我們?cè)陧?xiàng)目中集成了 Swagger 框架之后，運(yùn)行項(xiàng)目之后會(huì)為我們生成 Swagger-ui 界面，我們都知道這個(gè)界面還是相對(duì)美觀一些的，我們也可以直接在這個(gè)界面上瀏覽接口和其他信息。

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

這就表明，如果我們項(xiàng)目中的接口需求發(fā)生了變動(dòng)，我們可以直接在 Swagger Editor 中修改相應(yīng)的配置信息，并且可以實(shí)時(shí)看到修改結(jié)果，這對(duì)開發(fā)人員來(lái)說(shuō)是一個(gè)’福音’。

4. 學(xué)習(xí)基礎(chǔ)

1. 學(xué)習(xí) Swagger Editor 這個(gè)工具和 Swagger Codegen 一樣，需要大家真實(shí)開發(fā)過(guò)項(xiàng)目并且對(duì)項(xiàng)目進(jìn)行過(guò)簡(jiǎn)單的配置，并且使用的是 Java 7 或以上的 JDK 版本。

2. 如果你是一名后端開發(fā)人員，那么相信你在學(xué)習(xí) Swagger Editor 時(shí)會(huì)信手拈來(lái)。

5. 小結(jié)

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