三分鐘快速掌握Swagger入門技巧

現在開發，很多采用前後端分離的模式，前端只負責調用接口，進行渲染，前端和後端的唯一聯繫，變成了API接口。因此，API文檔變得越來越重要。swagger是一個方便我們更好的編寫API文檔的框架，而且swagger可以模擬http請求調用。

大部分採取的方式：Vue + SpringBoot，Vue通過js渲染頁面，後端把數據傳遞給js，早期前端只負責寫頁面，然後把寫好的HTML頁面給後端，後端使用模板引擎（Jsp，Thymeleaf、 freemarker）進行開發。

前後端分離的好處：各自開發，相對獨立，松耦合，前後端通過API進行交互，後端提供接口給前端，前端去調用該接口，但可能會導致前後端團隊人員不能做到及時協商，出現一些問題。解決方式：早期使用實時更新文檔，但非常繁瑣，後來又使用postman來進行一些測試。

swagger是目前最流行的Api框架，官網：https://swagger.io/

springboot中集成swagger使用步驟：

1.創建springboot工程，然後導入依賴

<dependency>

<groupId>io.springfoxgroupId>

<artifactId>springfox-swagger-uiartifactId>

<version>2.9.2version>

dependency>

<dependency>

<groupId>io.springfoxgroupId>

<artifactId>springfox-swagger2artifactId>

<version>2.9.2version>

dependency>

2.創建配置類

@Configuration

@EnableSwagger2//開啟Swagger2

public class SwaggerConfig {

}

然後啟動測試運行，訪問：http://localhost:8080/swagger-ui.html，看到如下頁面：

3.手動配置實例，修改SwaggerConfig配置類

package com.qf.swagger.config;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket

@Configuration

@EnableSwagger2//開啟Swagger2

public class SwaggerConfig {

//配置Swagger的Bean實例

@Bean

public Docket swaggerSpringMvcPlugin() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo());

}

//配置API的基本信息（會在http://項目實際地址/swagger-ui.html頁面顯示）

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("測試API文檔標題")

.description("測試api接口文檔描述")

.termsOfServiceUrl("http://www.baidu.com")

.version("1.0")

.build();

}

}

然後再次重啟測試運行：

4.創建實體類

package com.qf.swagger.entity;

import io.swagger.annotations.ApiModel;

import io.swagger.annotations.ApiModelProperty;

@ApiModel("用戶實體類")

public class User {

@ApiModelProperty("用戶名")

private String username;

@ApiModelProperty(

private String password;

public String getUsername() {

return username;

}

public void setUsername(String username) {

this.username = username;

}

public String getPassword() {

return password;

}

public void setPassword(String password) {

this.password = password;

}

}

5.創建controller

package com.qf.swagger.controller;

import com.qf.swagger.entity.User;

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiOperation;

import io.swagger.annotations.ApiParam;

import org.springframework.web.bind.annotation.GetMapping;

import

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RestController;

//@Api(description = "用戶接口")

@Api(tags = "用戶接口")

@RestController

public class UserController {

@ApiOperation("添加用戶")

@PostMapping("/add")

public User add(@RequestParam @ApiParam("用戶名") String username,@ApiParam("密碼") String password){

return new User();

}

@ApiOperation("修改用戶")

@PostMapping("/update")

public String update(){

return "修改";

}

@ApiOperation("刪除用戶")

@GetMapping("/delete")

public Boolean delete(@RequestParam @ApiParam("用戶編號") Integer id){

return true;

}

@ApiOperation("查詢用戶")

@RequestMapping("/query")

public User query(){

User user = new User();

user.setUsername("jack");

user.setPassword("1234");

return user;

}

}

6.修改SwaggerConfig配置類

package com.qf.swagger.config;

import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration

@EnableSwagger2//開啟Swagger2

public class SwaggerConfig {

//配置Swagger的Bean實例

@Bean

public

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

.groupName("yangl")//分組名稱(可以創建多個Docket就有多個組名)

.enable(true)//enable表示是否開啟Swagger

.select()

//RequestHandlerSelectors指定掃描的包

.apis(RequestHandlerSelectors.basePackage("com.qf.swagger.controller"))

.build();

}

//配置API的基本信息（會在http://項目實際地址/swagger-ui.html頁面顯示）

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("測試API文檔標題"

.description("測試api接口文檔描述")

.termsOfServiceUrl("http://www.baidu.com")

.version("1.0")

.build();

}

}

運行springboot的啟動類，訪問：http://localhost:8080/swagger-ui.html#/

swagger可以完全替代postman測試工具，進行對你編寫的接口進行測試

swagger通過註解表明該接口會生成文檔，包括接口名、請求方法、參數、返回信息

@Api：修飾整個類，描述Controller的作用

@ApiOperation：描述一個類的一個方法，或者說一個接口

@ApiModel：用對象來接收參數 ，修飾類

@ApiModelProperty：用對象接收參數時，描述對象的一個字段

@ApiResponse：HTTP響應其中1個描述

@ApiResponses：HTTP響應整體描述，一般描述錯誤的響應

@ApiIgnore：使用該註解忽略這個API

@ApiError ：發生錯誤返回的信息

@ApiParam：單個參數描述

@ApiImplicitParam：一個請求參數，用在方法上

@ApiImplicitParams：多個請求參數

閱讀更多 Java程序員一枚 的文章

關鍵字: JSP 三分鐘 官網