Swagger

時間 2019-11-21

標籤 swagger 简体版

原文原文鏈接

1.swagger介紹html

如今開發，不少採用先後端分離的模式，前端只負責調用接口，進行渲染，前端和後端的惟一聯繫，變成了API接口。所以，API文檔變得愈來愈重要。swagger是一個方便咱們更好的編寫API文檔的框架，並且swagger能夠模擬http請求調用。前端

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

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

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

2.springboot中集成swagger使用步驟：api

導入依賴springboot

<dependency>
<groupId>io.springfox</groupId>

app

<artifactId>springfox-swagger-ui</artifactId>

框架

<version>2.9.2</version>

前後端分離

</dependency>

<dependency>
<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.9.2</version>

</dependency>

建立配置類

@Configuration
@EnableSwagger2

開啓Swagger2

public class SwaggerConfig {

}

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

手動配置實例，修改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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@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();
}
}

而後再次重啓測試運行：

建立實體類

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;
}
}

建立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 org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(description ="用戶管理API")
@RestController
public class UserController {

@ApiOperation("添加用戶")
@PostMapping("/add")
public User add(@ApiParam("用戶名") String username,@ApiParam("密碼") String password){

return new User();
}

@ApiOperation("修改用戶")
@PostMapping("/update")
public String update(){
return "修改";
}

@ApiOperation("刪除用戶")
@GetMapping("/delete")
public Boolean delete(@ApiParam("用戶編號") Integer id){
return true;

}

@ApiOperation("查詢用戶")
@RequestMapping("/query")
public User query(){

User user = new User();
user.setUsername("jack");
user.setPassword("1234");

return user;
}
}

修改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.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