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

<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

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 中

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 代码

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 端口：

server:
  address: 127.0.0.1
  port: 80

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