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

开启Swagger2

public class SwaggerConfig {

配置Swagger的Bean实例

@Bean

public Docket swaggerSpringMvcPlugin() {

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页面显示）

swagger经过注解代表该接口会生成文档，包括接口名、请求方法、参数、返回信息

@Api：修饰整个类，描述Controller的做用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiModel：用对象来接收参数，修饰类

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应总体描述，通常描述错误的响应

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiParam：单个参数描述

@ApiImplicitParam：一个请求参数，用在方法上

@ApiImplicitParams：多个请求参数