SpringMVC 中配置 Swagger 插件的教程(分享)

2024-07-13 10:15:25

字體：大中小

來源：轉載

供稿：網友

一、簡介

Swagger的目標是為REST API定義一個與語言無關的標準接口，允許用戶發現和理解計算機服務的功能，而無需訪問源代碼。當通過Swagger正確定義時，用戶可以用最少量的實現邏輯理解遠程服務并與之交互。類似于低級編程所做的接口。

二、實現步驟

1、添加 Maven 依賴

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version></dependency>

2、Swagger 配置類

@Configuration@EnableSwagger2//@ComponentScan(basePackageClasses = JgBjBaseInfoCompanyApi.class) 或者@ComponentScan(basePackages = "com.summersoft.ts.schedule.supervision.controller") //要掃描的包路徑public class SwaggerConfig { @Bean public Docket swaggerSpringMvcPlugin() { return new Docket(DocumentationType.SWAGGER_2)  .apiInfo(apiInfo())  .select() //選擇哪些路徑和api會生成document  .apis(RequestHandlerSelectors.any())//對所有Api進行監控  .paths(PathSelectors.any()) //對所有路徑進行掃描  .build(); } /** * api具體信息 * * @return */ private ApiInfo apiInfo() { ApiInfo apiInfo = new ApiInfo(  "對接服務平臺API文檔", //標題  "", //描述  "1.0", //版本  "",  "",  "", //簽名  "" //簽名鏈接 ); return apiInfo; }}

3、Swagger 注解

Swagger 會去掃描SwaggerConfig 中配置的包路徑下的帶有Swagger 注解的類文件，并最后生成一串掃描的Json文件...

Swagger 注解說明：https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

@Api :用在類上，說明該類的作用,需要說明的是較老的版本用的value表示掃描生成的類名，1.5后要用tag 表示類名

@Api(tag= "UserController", description = "用戶相關api")

@ApiOperation :用在方法上，說明方法的作用

@ApiOperation(value = "查找用戶", notes = "查找用戶", httpMethod = "GET", produces =

MediaType.APPLICATION_JSON_UTF8_VALUE)

@ApiParam ：用在參數列表中，表明參數的含義

@ApiParam(value = "創建或更新距離當前時間(月)") Integer time

@ApiImplicitParams :用在方法上包含一組參數說明

@ApiImplicitParam :用在@ApiImplicitParams注解中，指定一個請求參數的各個方面

paramType：參數放在哪個地方

header–>請求參數的獲?。篅RequestHeader

query–>請求參數的獲取：@RequestParam

path（用于restful接口）–>請求參數的獲?。篅PathVariable

body（不常用）

form（不常用）

name：參數名

dataType：參數類型

required：參數是否必須傳

value：參數的意思

defaultValue：參數的默認值

@ApiImplicitParams({

@ApiImplicitParam(name = "id", value = "唯一id", required = true, dataType = "Long", paramType = "path"),
})

@ApiResponses :用于表示一組響應

@ApiResponse :用在@ApiResponses中，一般用于表達一個錯誤的響應信息

code：數字，例如400

message：信息，例如”請求參數沒填好”

response：拋出異常的類

@ApiResponses(value = {
@ApiResponse(code = 400, message = "No Name Provided")
})

@ApiModel :描述一個Model的信息（這種一般用在post創建的時候，使用@RequestBody這樣的場景，請求參數無法使用@ApiImplicitParam注解進行描述的時候）

@ApiModel(value = "用戶實體類")

@ApiModelProperty :描述一個model的屬性

@ApiModelProperty(value = "登錄用戶")

SpringMVC,配置,Swagger

三、swagger-ui

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

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

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

比如我的url值為：

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

SpringMVC,配置,Swagger