2. 程式人生 > >如何優雅的“編寫”api介面文件

如何優雅的“編寫”api介面文件

阿新 • • 發佈：2018-12-24

前言

　　今天我需要把之前寫的介面整理成文件，老大給了意見用swagger搞，我像發現新大陸一樣的興奮，迫不及待得去“佔有”它。 
　　Swagger很容易上手，我花了十幾分鍾就搞定了。正好接著之前的如何優雅的格式化介面，這裡再說一下SpringBoot整合Swagger的簡單過程吧

Swagger介紹

　　每每get新的技能想分享的時候，按照套路來講，需要有一個版塊將該技能的“前世今生”介紹個遍，但就我接觸到完成配置不超過半小時，我覺得讓我完完整整的介紹有點太虛了，所以，最好的介紹就是下面的官網 
http://swagger.io/ 
http://swagger.io/irc/ 這個是實時聊天室，剛剛和老外溝通了一番“how are you？fine thk you.and you?” 

https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel 這個是一些註解的api 
Swagger有三個模組

  • Swagger Editor
  • Swagger UI

  • Swagger Codegen

    　　我使用的是Swagger UI，我個人的理解就是“使用Swagger相關的註解並啟動服務後，就可以在對應的頁面檢視API並測試”，先看一下最終的介面 
    　　 
    api.png
    介面描述、引數型別、返回示例線上除錯都給你搞定了。你還在猶豫什麼，趕快checkou程式碼，試一試吧

整合

　　我接著之前的程式碼的寫(可以在我的GitHub上瀏覽，或者直接clone到本地再切換到api-norms

分支)，這裡要說一下，使用Springboot整合Swagger賊JB簡單，相比較而言，SpringMVC就比較複雜了，這裡暫且不談（以後可能也不會談了，自從我使用了Springboot之後，就已經開始拋棄SpringMVC了）

maven依賴

老規矩上配置

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version
 
>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10

新增Swagger註解

　　在Application上直接新增@EnableSwagger2，注意版本，官網上的版本還沒有更新到最新的，最新的在Github上看,配置後的程式碼

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Created by wangxc on 2017/3/9.
 */
@SpringBootApplication
@EnableSwagger2
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16

可以了，接下來就是描述介面的註解了！在Controller層，做如下配置

package com.quick.api;


import com.quick.po.Address;
import com.quick.utils.BaseResp;
import com.quick.utils.ResultStatus;
import io.swagger.annotations.*;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.ArrayList;
import java.util.List;

/**
 * Created with IDEA
 * User: vector
 * Data: 2017/4/12
 * Time: 8:41
 * Description:
 */
@RestController
@RequestMapping("/api")
@Api("springboot整合swagger2") // Swagger UI 對應api的標題描述
public class WebController {

    @ApiOperation("獲取地址資訊") // 單個介面的描述
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="query",name="province",dataType="String",required=true,value="省",defaultValue="廣東省"),// 每個引數的型別，名稱，資料型別，是否校驗，描述，預設值(這些在介面上有展示)
            @ApiImplicitParam(paramType="query",name="area",dataType="String",required=true,value="地區",defaultValue="南山區"),
            @ApiImplicitParam(paramType="query",name="street",dataType="String",required=true,value="街道",defaultValue="桃園路"),
            @ApiImplicitParam(paramType="query",name="num",dataType="String",required=true,value="門牌號",defaultValue="666")
    })
    @ApiResponses({
            @ApiResponse(code=400,message="請求引數沒填好"), // 響應對應編碼的描述
            @ApiResponse(code=404,message="請求路徑沒有或頁面跳轉路徑不對")
    })
    @RequestMapping(value = "/address",method = RequestMethod.POST)
    public BaseResp<Address> getAddressInfo(@RequestParam(value = "province")String province,
                                   @RequestParam(value = "area")String area,
                                   @RequestParam(value = "street")String street,
                                   @RequestParam(value = "num")String num){

        if(StringUtils.isEmpty(province)||StringUtils.isEmpty(area)||StringUtils.isEmpty(street)||StringUtils.isEmpty(num)){
            return new BaseResp(ResultStatus.error_invalid_argument);
        }
        Address address = new Address();
        address.setProvince(province);
        address.setArea(area);
        address.setStreet(street);
        address.setNum(num);
        return new BaseResp(ResultStatus.SUCCESS,address);

    }

    @ApiOperation("獲取地址資訊")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="query",name="province",dataType="String",required=true,value="省",defaultValue="廣東省"),
            @ApiImplicitParam(paramType="query",name="area",dataType="String",required=true,value="地區",defaultValue="南山區"),
            @ApiImplicitParam(paramType="query",name="street",dataType="String",required=true,value="街道",defaultValue="桃園路"),
            @ApiImplicitParam(paramType="query",name="num",dataType="String",required=true,value="門牌號",defaultValue="666")
    })
    @ApiResponses({
            @ApiResponse(code=400,message="請求引數沒填好"),
            @ApiResponse(code=404,message="請求路徑沒有或頁面跳轉路徑不對")
    })
    @RequestMapping(value = "/address/list",method = RequestMethod.POST)
    public BaseResp<List<Address>> getAddressList(@RequestParam(value = "province")String province,
                                             @RequestParam(value = "area")String area,
                                             @RequestParam(value = "street")String street,
                                             @RequestParam(value = "num")String num){

        if(StringUtils.isEmpty(province)||StringUtils.isEmpty(area)||StringUtils.isEmpty(street)||StringUtils.isEmpty(num)){
            return new BaseResp(ResultStatus.error_invalid_argument);
        }
        Address address = new Address();
        address.setProvince(province);
        address.setArea(area);
        address.setStreet(street);
        address.setNum(num);
        List<Address> lists = new ArrayList<>();
        lists.add(address);
        lists.add(address);
        lists.add(address);
        return new BaseResp(ResultStatus.SUCCESS,lists);

    }
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
  • 55
  • 56
  • 57
  • 58
  • 59
  • 60
  • 61
  • 62
  • 63
  • 64
  • 65
  • 66
  • 67
  • 68
  • 69
  • 70
  • 71
  • 72
  • 73
  • 74
  • 75
  • 76
  • 77
  • 78
  • 79
  • 80
  • 81
  • 82
  • 83
  • 84
  • 85
  • 86
  • 87
  • 88
  • 89
  • 90

我只是在原來的基礎上添加了下面註解

名稱解釋
@Api()將類標記為一種Swagger資源。
@ApiOperation()描述針對特定路徑的操作或通常是 http 方法。
@ApiImplicitParams允許多個 ApiImplicitParam 物件列表的包裝。
@ApiImplicitParam表示 api 操作中的單個引數。
@ApiResponses允許多個 ApiResponse 物件列表的包裝。
@ApiResponse描述操作的可能響應。

更多的看這裡

就這麼簡單，一個基本而又強大的API文件就整理好了！

啟動

正常的啟動SpringBoot,你會發現控制檯輸出了這些內容

2017-05-03 21:42:52,975  INFO ClassOrApiAnnotationResourceGrouping:100 - Group for method getAddressList was springboot整合swagger2
2017-05-03 21:42:52,986  INFO ClassOrApiAnnotationResourceGrouping:100 - Group for method getAddressList was springboot整合swagger2
  • 1
  • 2

說明Swagger已經成功跑起來了，接下來開啟瀏覽器，輸入你連結 
yourdomain/swagger-ui.html 
我的是

相信你看了介面並四處點點之後，就會對上面註解的含義有了更進一步的瞭解~

後記

　　這裡展示的只是Swagger最基本的功能，更多強大的功能如果後面有運用，我會持續更新的。 
　　目前我在看api尋找SwaggerUI輸入檔案的測試，因為我有個介面需要上傳檔案，等我搞定，再來分享吧！！！ 
　　

歡迎進入我的個人部落格瀏覽

相關推薦

如何優雅的“編寫”api介面文件

前言　　今天我需要把之前寫的介面整理成文件，老大給了意見用swagger搞，我像發現新大陸一樣的興奮，迫不及待得去“佔有”它。 　　Swagger很容易上手，我花了十幾分鍾就搞定了。正好接著之前的如何優雅的格式化介面，這裡再說一下SpringBoot整合Swagger的簡單過

Swagger2整合springBoot,自動生成API介面文件

Swagger2整合springBoot 首先匯入jar包 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swa

Swagger 生成 PHP API 介面文件

Swagger 生成 PHP API 介面文件 標籤（空格分隔）： php 1、概況 有同學反饋寫幾十個介面文件需要兩天的工作量, 隨著多部門之間的協作越來越頻繁, 維護成本越來越高, 文件的可維護性越來越差, 需要一個工具來管理這些介面的文件, 並能夠充當mock server給呼叫方使用。 有

整合swagger2生成Restful Api介面文件 webapi文件描述-swagger

整合swagger2生成Restful Api介面文件 swagger Restful文件生成工具 2017-9-30 官方地址：https://swagger.io/docs/specification/about/ 官方Github：https://github.com/swagger-

API介面文件說明

API文件規範要求 一、 寫明該介面的功能是什麼 二、 請求的URL是什麼 三、 請求方式是什麼（POST、GET、 DELETE、PUT、 PATCH等） 四、 引數是什麼，此處還需說明你的引數名、引數型別、是否必填、引數的簡單解釋 五、 請求成功時的響應內容（實際開發中，要與前端同事溝通

Swagger2 快速定義API介面文件

引入依賴 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0&

Spring專案整合apidoc生成api介面文件

一、背景需求  JavaWeb/spring專案寫成的api介面，需要自動生成api文件，甚至需要線上測試介面。考慮實現的方案有swagger，apidoc，spring rest docs。在之後的專案都有一一嘗試，最終還是覺得apidoc的方式比較合適，雖然有一些問題（針對線上

好用的API介面文件推薦總結

我是做服務端開發的，經常需要些介面文件，以前用過txt，word，感覺體驗太差了。網上找過很多，下面給大家總結一下。 易文件應該是我用過體驗最好的線上介面文件，專門優化過的http文件編輯和預覽頁面，編寫很方便，預覽很漂亮，還支援線上介面除錯。另外還有一些很方便的小功能，感覺用了就回不去了。 Showdo

swagger 生成 PHP restful API 介面文件

需求: 為客戶端同事寫介面文件的各位後端同學,已經在各種場合回憶了使用自動化文件工具前手寫文件的血淚史. 我的故事卻又不同,因為首先來說,我在公司是 Android 組負責人,屬於上述血淚史中催死人不償命的客戶端陣營. 但血淚史卻是相通的,沒有自動化文件的日子,對介面

Spring Cloud Zuul中使用Swagger彙總API介面文件

有很多讀者問過這樣的一個問題：雖然使用Swagger可以為Spring MVC編寫的介面生成了A

bigemap百度離線地圖API介面文件及介面呼叫例項

    1.當前版本支援百度電子地圖瓦片和百度衛星地圖瓦片； 2.效果預覽演示地址：http://www.bigemap.com/bmap  後臺編輯體驗地址：http://www.bigemap.com/bmap/ 可隨意在後臺新增/修改標註

.NET Core使用swagger進行API介面文件管理

一、問題背景 　　隨著技術的發展，現在的開發模式已經更多的轉向了前後端分離的模式，在前後端開發的過程中，聯絡的方式也變成了API介面，但是目前專案中對於API的管理很多時候還是通過手工編寫文件，每次的需求變更只要涉及到介面的變更，文件都需要進行額外的維護，如果有哪個小夥伴忘記維護，很多時候就會造

【流程規範】API介面文件規範

介面名稱 前置主動還款申請(/payBill) 介面描述 返回格式：json 請求方式：GET/ POST 介面備註：根據傳入的key和qq號碼發起還款的申請 請

swagger-ui教程 構建api介面文件工具

1.在我第一次開發app後端的時候，使用的word文件，就是我先將所有資料格式定義好，會返回什麼樣的資料寫好。前端人員照這個來進行開發。貼一張圖吧： PS:存在的問題：①介面改動時，不易被識別。②維護困難，不便於查詢。③前端開發不能進行測試。(如果還要寫

Swagger UI教程 API 文件神器 搭配Node使用 web api 介面文件 mvc介面文件

兩種方案 一、Swagger 配置 web Api 介面文件美化 二、通過NodeJS 釋出Swagger UI 配置api 文件 先說一下簡單的 Swagger 配置 web Api  Swagger-UI本身只提供線上測試功能，要整合它還需要告訴它本專案提供的各

谷歌離線地圖API介面文件及介面呼叫例項

相關教程：說明：1. 當前版本支援 谷歌電子/衛星地圖瓦片、高德地圖、阿里雲地圖、超圖、騰訊地圖等（只需下載該地圖源的瓦片拷貝到指定目錄即可）；（只下載了部分谷歌地圖瓦片作為離線樣本，某些地方無法顯示視為正常，包含全國4-12級，部分成都13-16級）3.  我們可以提供離線

API介面文件生成方案調研

1調研背景目前存在以下情況:1）一般開發人員更新介面後，沒有同時更新rap，rap上的介面定義普遍存在跟程式碼不一致的情況。2）後端開發人員檢視別人介面，很難很快地知道介面的作用，以及介面入參和返回結果中每個欄位的含義。3）rap上的mock資料功能不是特別好用。2 調研結果

Swagger2+SpringMVC 生成API介面文件

簡單記錄一下配置的過程 - 匯入包 - 寫個配置類 - 在Controller層用註解進行註釋 - 通過一個URL就可以看到api介面文件 jar包

D3.js中文版api-介面文件

Api參考 此文件翻譯自 API Reference （英語），版本為 2013-9-9 。不能保證文件的同步更新，因此，需要了解最新的開發特性，請移步英文版 API 參考 。 d3 庫所提供的所有 API 都在 d3 名稱空間下。d3 庫使用語義版本命名法（semantic versioni

如何優雅的生成介面文件？

　　我們知道在專案開發階段，介面文件基本上是必備產物了，一般由後端開發人員提供，作為和前端人員進行前後端介面聯調的橋樑，或者與別的專案模組進行互動提供指導等等，介面文件的準確性，實時性，詳細與否等，都會極大的影響前面的操作。那麼如何才能優雅的生成介面文件呢？ 　　這裡，我首先給出如何生成介面文件的小demo