五分钟搞定swagger

番茄果子
350 阅读3分钟

前言：前后端分离开发过程中，后端程序员还在自己手动书写和维护接口文档吗？或者后端还在用postman进行接口测试吗？花五分钟看完这篇文章，swagger轻松帮你搞定。

1. swagger是什么?

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

2. swagger的用途

后端开发：不用手写API文档、可用来测试接口

前端开发：通过SWAGGER查看后端接口传参方式和要求返回的数据格式

3. 如何配置swagger

swagger完全由后端开发人员去配置。配置非常非常简单，三步搞定：

3.1 maven导入依赖：pom.xml文件中添加：springfox-swagger2 和 springfox-swagger-ui

3.2 添加2个配置文件：项目包目录下创建config文件夹，在config文件夹下添加SwaggerConfig.java 和 WebMvcConfig.java文件，路径如下图：

SwaggerConfig.java内容如下：

package com.xiaomi.swagger_test.config;  //改一下包名

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
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  //开启swagger
@EnableWebMvc   //添加
@ComponentScan(basePackages = { "org.woodwhales.king.controller" })
@Profile({"dev"})  //设置swagger只在开发阶段生效
public class SwaggerConfig {
	@Bean
	public Docket customDocket() {
    	return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
	}
	private ApiInfo apiInfo() {  
	    //填写项目基本信息（可选填）
    	Contact contact = new Contact("jintian", "10.234.199.155", "jintian3@xiaomi.com");
    	return new ApiInfoBuilder().title("swagger入门教程").contact(contact).description("这里是 RESTful API 描述").version("1.0.1").build();
	}
}

WebMvcConfig.java内容如下：

package com.xiaomi.swagger_test.config;  //改一下包名，其他不用修改

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/");
	}
}

3.3 controller层添加注释

在controller层每个方法之前添加注释@ApiOperation，@ApiImplicitParam，前者是对方法添加描述，后者表示该方法需要传参。具体见下图：

package com.xiaomi.swagger_test.controller;

import java.util.ArrayList;
import java.util.Date;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
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 com.xiaomi.swagger_test.dao.IUserDao;
import com.xiaomi.swagger_test.pojo.User;

//引入swagger注释符号
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;

@RequestMapping("/users")
@RestController
@Api(value = "用户模块")  //注释模块名称
public class UserController {
	@Autowired
	private IUserDao dao;
        //通过@ApiOperation添加该方法的描述
	@ApiOperation(value = "获取用户列表", notes = "获取所有用户的列表")
	@GetMapping("/")
	public ResponseEntity<?> users() {
    	List<User> users = dao.findAll();
    	return ResponseEntity.ok(users);
	}
         //通过@ApiOperation添加该方法的描述
	@ApiOperation(value = "用户详情", notes = "根据id获取用户")
	 //通过@ApiImplicitParam表示该方法的传参方式，paramType="path"为get请求的传参
	@ApiImplicitParam(value = "用户的id", paramType = "path")
	@GetMapping("/get/{id}")
	public User getUserById(@PathVariable("id") int id) {
    	User user = dao.findById(id);
    	return user;
	}

	@ApiOperation(value = "删除用户", notes = "根据id删除用户")
	@ApiImplicitParam(value = "用户的id", paramType = "path")
	@GetMapping("/delete/{id}")
	public User deleteUserById(@PathVariable("id") int id) {
    	dao.deleteUser(id);
    	return null;
	}

	@ApiOperation(value = "新增用户", notes = "新增一条用户信息")
	//通过@ApiImplicitParam表示该方法的传参方式，paramType="query"为post请求的传参
	@ApiImplicitParam(value = "一条新增用户信息", paramType = "query")
	@PostMapping("/addUser/")
	public User addUser(@RequestBody User user) {
    	dao.addUser(user);
    	return user;
	}
	
	@ApiOperation(value = "更新用户", notes = "更新一条用户信息")
	@ApiImplicitParam(value = "一条更改后的用户信息", paramType = "query")
	@PostMapping("/updateUser/")
	public User updateUser(@RequestBody User user) {
    	dao.updateUser(user);
    	return user;
	}
}
  1. 启动你的java项目，访问localhost:端口号/swagger-ui.html就可以看到如下图的api文档了。后续，如果后端修改了接口信息，swagger文档会自动更新，不需额外的手动修改。小小工具，给开发过程带来大大的便捷。

下期预告：jenkins

avatar
文章
阅读
粉丝