swagger入门教程

前言

Swagger 能成为最受欢迎的 RESTful APIs 文档生成工具之一,有以下几个原因:

  • Swagger 可以生成一个具有互动性的 API 控制台,开发者可以用来快速学习和尝试 API。
  • Swagger 可以生成客户端 SDK 代码用于各种不同的平台上的实现。
  • Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
  • Swagger 有一个强大的社区,里面有许多强悍的贡献者。

Swagger 文档提供了一个方法,使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API,包括了比如 names、order 等 API 信息。

用 Swagger 文件生成互动的 API 文档是最精简的,它展示了资源、参数、请求、响应。但是它不会提供你的API如何工作的其他任何一个细节。

一、maven 工程依赖

引入 jar 文件:springfox-swagger2、springfox-swagger-ui

1
2
3
4
5
6
7
8
9
10
11
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>

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

二、swagger 全局配置

2.1 创建 config 目录,新建 swagger 的配置文件 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
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@EnableWebMvc
@ComponentScan(basePackages = {"org.woodwhales.king.controller"})
public class SwaggerConfig {
@Bean
public Docket customDocket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

private ApiInfo apiInfo() {
Contact contact = new Contact("woodwhale", "http://127.0.0.1/", "woodwhales.github.io");
return new ApiInfoBuilder()
.title("swagger入门教程")
.contact(contact)
.description("这里是 RESTful API 描述")
.version("1.0.1").build();
}
}

2.2 在 config 目录中,继续创建 WebMvcConfig.java 配置文件,将 swagger-ui 页面注入到 spring 中

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");

registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}

以上配置的资源是在springfox-swagger-ui.jar jar 文件中,这个 jar 包只有 META-INF 目录。

三、编写 RESTful 接口

编写 controller 代码

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
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.woodwhales.king.entity.User;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;

@RequestMapping("/users")
@RestController
@Api(value = "用户模块", description = "用户模块的接口")
public class UserController {

public static List<User> users = new ArrayList<>();

static {
users.add(new User(1L, "Tom", 12));
users.add(new User(2L, "Tina", 11));
}

@ApiOperation(value = "获取用户列表", notes = "获取所有用户的列表")
@GetMapping("/")
public Object users() {
Map<String, Object> map = new HashMap<>();
map.put("users", users);
return map;
}

@ApiOperation(value = "用户详情", notes = "根据id获取用户")
@ApiImplicitParam(value = "用户的id", paramType = "path")
@GetMapping("/{id}")
public User getUserById(@PathVariable("id") int id) {
return users.get(id);
}

@ApiOperation(value = "创建用户", notes = "新增用户")
@ApiImplicitParam(value = "用户对象", paramType = "query")
@PostMapping("/")
public Object addUser(@RequestBody User user) {
return users.add(user);
}
}

在 application.yml 中配置 web 端口:

1
2
3
server:
address: 127.0.0.1
port: 80

访问:http://127.0.0.1:80/swagger-ui.html

访问swagger-ui

updated updated 2024-01-05 2024-01-05
本文结束感谢阅读

本文标题:swagger入门教程

本文作者:

微信公号:木鲸鱼 | woodwhales

原始链接:https://woodwhales.cn/2019/03/06/024/

许可协议: 署名-非商业性使用-禁止演绎 4.0 国际 转载请保留原文链接及作者。

0%