Spring Boot Swagger

Spring Boot Swagger 入门实战

Posted by leone on 2018-02-16

Spring Boot Swagger

开发环境

开发工具: Intellij IDEA 2018.2.6

springboot: 2.0.7.RELEASE

jdk: 1.8.0_192

maven: 3.6.0

swagger: 2.9.2

swagger 简介

什么是 swagger ?

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。

Swagger是一组开源项目,其中主要模块如下:

  • Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。

  • Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。

  • Swagger-js: 用于JavaScript的Swagger实现。

  • Swagger-node-express: Swagger模块,用于node.js的Express web应用框架。

  • Swagger-ui:一个无依赖的HTML、JS和CSS集合,可以为Swagger兼容API动态生成优雅文档。

  • Swagger-codegen:一个模板驱动引擎,通过分析用户Swagger资源声明以各种语言生成客户端代码。

搭建项目

  • pom.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<parent>
<artifactId>spring-boot-examples</artifactId>
<groupId>com.andy</groupId>
<version>1.0.7.RELEASE</version>
</parent>
<modelVersion>4.0.0</modelVersion>

<artifactId>spring-boot-swagger</artifactId>

<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.spring.platform</groupId>
<artifactId>platform-bom</artifactId>
<version>Cairo-SR7</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>

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

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>

</dependencies>


<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.0</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
<encoding>UTF-8</encoding>
</configuration>
</plugin>

<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<!--<mainClass>${start-class}</mainClass>-->
<layout>ZIP</layout>
</configuration>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>

</project>
  • application.yml
1
2
3
4
# swagger 无须太多配置这里只是简单的配置了工程名
swagger:
# 是否让浏览器可以访问swagger页面
show: true
  • 启动类
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
* @author Leone
* @since 2018-05-29
**/
@EnableSwagger2
@SpringBootApplication
public class SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class);
}
}
  • SwaggerConfig.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
import com.google.common.base.Predicates;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.Collections;

import static springfox.documentation.builders.RequestHandlerSelectors.basePackage;

/**
* @author Leone
* @since 2018-07-12
**/
@Component
public class SwaggerConfig {

@Value("${swagger.show}")
private Boolean enable;

@Bean
public Docket swaggerApi() {
Parameter parameter = new ParameterBuilder()
.name("Authorization")
.description("token")
.modelRef(new ModelRef("string"))
.parameterType("header")
.required(false)
.defaultValue("token ")
.build();
return new Docket(DocumentationType.SWAGGER_2)
.enable(enable)
.apiInfo(apiInfo())
.groupName("web-API")
.globalOperationParameters(Collections.singletonList(parameter))
.select()
.apis(basePackage("com.andy"))
.paths(Predicates.alwaysTrue())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("API")
.description("web接口文档")
.version("v1.0.0")
.termsOfServiceUrl("http://www.baidu.com")
.contact(new Contact("leone", "https://leone.com", "leone@gmail.com"))
.license("Apache2.0")
.licenseUrl("http://www.apache.org")
.build();
}
}
  • ApiController.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
import com.andy.swagger.entity.UserDTO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

/**
* @author Leone
* @since 2018-07-12
**/
@RestController
@Api(tags = "文档接口:crud测试")
@RequestMapping("/api/user")
public class ApiController {

@ApiOperation("查询用户列表")
@GetMapping("/list")
public String list(@ApiParam("当前页") @RequestParam Integer page, @RequestParam Integer size) {
return "list";
}

@ApiOperation("保存用户")
@PostMapping
public String save(@RequestBody UserDTO userForm) {
return "save";
}

@ApiOperation("删除用户")
@DeleteMapping
public String delete() {
return "delete";
}

@ApiOperation("修改用户")
@PutMapping
public String update() {
return "update";
}

}
  • User.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
import java.io.Serializable;
import java.util.Date;

/**
* @author Leone
* @since 2018-07-12
**/
public class User implements Serializable {

private Long userId;

private String account;

private String password;

private String description;

private Integer age;

private Date createTime;

private boolean deleted;

public User() {
}

public User(Long userId, String account, String password, String description, Integer age, Date createTime, Boolean deleted) {
this.userId = userId;
this.account = account;
this.password = password;
this.description = description;
this.age = age;
this.createTime = createTime;
this.deleted = deleted;
}

// getset
}
  • UserService.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

package com.andy.swagger.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.util.Date;

/**
* @author Leone
* @since 2018-07-12
**/
@ApiModel
public class UserDTO {

@ApiModelProperty(value = "用户账号")
private String account;

@ApiModelProperty(value = "密码")
private String password;

@ApiModelProperty(value = "生日")
private Date birthday;

@ApiModelProperty(value = "工资")
private Double salary;

@ApiModelProperty(value = "创建时间")
private Date createTime;

@ApiModelProperty(value = "是否删除")
private Boolean deleted;

// getset

}
  • UserVO.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.util.Date;

/**
* @author Leone
* @since 2018-07-12
**/
@ApiModel
public class UserVO {

@ApiModelProperty(value = "主键",example = "1200L")
private Long userId;

@ApiModelProperty("账号")
private String account;

@ApiModelProperty("自我介绍")
private String description;

@ApiModelProperty("年龄")
private Integer age;

@ApiModelProperty("创建时间")
private Date createTime;

// getset

}

传送门