一、簡(jiǎn)介

swagger的目標(biāo)是為rest api定義一個(gè)與語(yǔ)言無(wú)關(guān)的標(biāo)準(zhǔn)接口，允許用戶(hù)發(fā)現(xiàn)和理解計(jì)算機(jī)服務(wù)的功能，而無(wú)需訪問(wèn)源代碼。當(dāng)通過(guò)swagger正確定義時(shí)，用戶(hù)可以用最少量的實(shí)現(xiàn)邏輯理解遠(yuǎn)程服務(wù)并與之交互。類(lèi)似于低級(jí)編程所做的接口。

二、實(shí)現(xiàn)步驟

1、添加 maven 依賴(lài)

2、swagger 配置類(lèi)

3、swagger 注解

swagger 會(huì)去掃描swaggerconfig 中配置的包路徑下的帶有swagger 注解的類(lèi)文件，并最后生成一串掃描的json文件...

swagger 注解說(shuō)明：https://github.com/swagger-api/swagger-core/wiki/annotations#apimodel

@api :用在類(lèi)上，說(shuō)明該類(lèi)的作用,需要說(shuō)明的是較老的版本用的value表示掃描生成的類(lèi)名，1.5后要用tag 表示類(lèi)名

@api(tag= "usercontroller", description = "用戶(hù)相關(guān)api")

@apioperation :用在方法上，說(shuō)明方法的作用

@apioperation(value = "查找用戶(hù)", notes = "查找用戶(hù)", httpmethod = "get", produces =

mediatype.application_json_utf8_value)

@apiparam ：用在參數(shù)列表中，表明參數(shù)的含義

@apiparam(value = "創(chuàng)建或更新距離當(dāng)前時(shí)間(月)") integer time

@apiimplicitparams :用在方法上包含一組參數(shù)說(shuō)明

@apiimplicitparam :用在@apiimplicitparams注解中，指定一個(gè)請(qǐng)求參數(shù)的各個(gè)方面

paramtype：參數(shù)放在哪個(gè)地方

header–>請(qǐng)求參數(shù)的獲?。篅requestheader

query–>請(qǐng)求參數(shù)的獲?。篅requestparam

path（用于restful接口）–>請(qǐng)求參數(shù)的獲?。篅pathvariable

body（不常用）

form（不常用）

name：參數(shù)名

datatype：參數(shù)類(lèi)型

required：參數(shù)是否必須傳

value：參數(shù)的意思

defaultvalue：參數(shù)的默認(rèn)值

@apiimplicitparams({

@apiimplicitparam(name = "id", value = "唯一id", required = true, datatype = "long", paramtype = "path"),
})

@apiresponses :用于表示一組響應(yīng)

@apiresponse :用在@apiresponses中，一般用于表達(dá)一個(gè)錯(cuò)誤的響應(yīng)信息

code：數(shù)字，例如400

message：信息，例如”請(qǐng)求參數(shù)沒(méi)填好”

response：拋出異常的類(lèi)

@apiresponses(value = {
@apiresponse(code = 400, message = "no name provided")
})

@apimodel :描述一個(gè)model的信息（這種一般用在post創(chuàng)建的時(shí)候，使用@requestbody這樣的場(chǎng)景，請(qǐng)求參數(shù)無(wú)法使用@apiimplicitparam注解進(jìn)行描述的時(shí)候）

@apimodel(value = "用戶(hù)實(shí)體類(lèi)")

@apimodelproperty :描述一個(gè)model的屬性

@apimodelproperty(value = "登錄用戶(hù)")

三、swagger-ui

有了上面的配置信息，swagger 就會(huì)幫我們掃描出所有的 類(lèi)信息，并生成一個(gè)json文件。想讓json文件友好的展示在人們面前，需要用到 swagger-ui 這個(gè)組件：

1、 swagger-ui 使用說(shuō)明：https://swagger.io/docs/swagger-tools/

2、下載 swagger-ui ,在webapp 目錄下新建一個(gè)swagger目錄，把 dist 目錄下的文件，放入swagger目錄下，并修改index.html文件，默認(rèn)是從連接 http://petstore.swagger.io/v2/swagger.json 獲取 api 的 json，這里需要將url值修改為 http://{ip}:{port}/{projectname}/api-docs的形式，{}中的值根據(jù)自身情況填寫(xiě)。

比如我的url值為：

http://localhost:8080/vouchers/api-docs 。另外，需要配置一下spring mvc的資源放行：<mvc:resources mapping="/swagger/**" location="/swagger/"/>

tips：默認(rèn)的dist 目錄下沒(méi)有這么多文件，swagger-ui 可以自定義配置，這個(gè)是我們項(xiàng)目中使用的，不用改項(xiàng)目名，項(xiàng)目名動(dòng)態(tài)獲?。篽ttps://files.cnblogs.com/files/jmcui/swagger.zip

3、swagger-ui 怎么對(duì)展示的接口排序：

apissorter ：對(duì)api /標(biāo)簽列表應(yīng)用排序。它可以是'alpha'（按名稱(chēng)排序）或函數(shù)（請(qǐng)參閱array.prototype.sort（）以了解sort函數(shù)的工作原理）。默認(rèn)是服務(wù)器返回的順序不變。

operationssorter ：對(duì)每個(gè)api的操作列表應(yīng)用一個(gè)排序。它可以是'alpha'（按字母數(shù)字排序），'method'（按http方法排序）或函數(shù)（參見(jiàn)array.prototype.sort（）來(lái)知道sort函數(shù)的工作方式）。默認(rèn)是服務(wù)器返回的順序不變。

以上這篇springmvc 中配置 swagger 插件的教程(分享)就是小編分享給大家的全部?jī)?nèi)容了，希望能給大家一個(gè)參考，也希望大家多多支持服務(wù)器之家。

原文鏈接：http://www.cnblogs.com/jmcui/archive/2017/12/24/8098268.html