接口文档生成工具Swagger2

时间 2020-06-22

标签接口文档生成工具 swagger2 swagger 繁體版

原文原文链接

前言：

　　在当下先后端分离开发和微服务大行其道的状况下，微服务及先后端分离后，先后端并行开发，这样沟通成本就增长了。因此一款强大的RESTful API文档就相当重要。而目前在后端领域，html

基本上是Swagger的天下了。前端

什么是Swagger?　　

　　Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。整体目标是使客户端和文件系统做为服务器以一样的速度来更新。java

文件的方法，参数和模型紧密集成到服务器端的代码，容许API来始终保持同步。spring

能够解决什么问题？

　　一、建立文档成本高：因为接口众多，而且细节复杂（须要考虑不一样的HTTP请求类型、HTTP头部信息、HTTP请求内容等）。json

　　二、维护文档成本高：修改接口实现的时候必须同步修改接口文档，而文档与代码可能存储于两个不一样的媒介，除非有严格的管理机制，不然易致使不一致现象。后端

　　三、沟通成本高：文档更新时，若不能及时交流，前端不能及时获取最新的接口信息。api

　　四、接口返回结果不明确，不能直接在线测试，一般需使用另外的工具，如：postman等。安全

做用：springboot

　　一、接口的文档在线自动生成。服务器

　　二、功能测试。

Swagger2经常使用注解有哪些？

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

@Api：修饰整个类，描述Controller的做用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应总体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

如何使用？（SpringBoot集成）

　　1)添加Maven依赖

<!--swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

　　2）建立配置类，并添加注解 @Configuration和定义Docket的bean类

　　　　注意：在与spring boot 集成时，放在与application.java 同级的目录下

　　　　　　经过@Configuration注解，让spring来加载该配置

　　　　　　用@Configuration注解该类，等价于XML中配置beans；用@Bean标注方法等价于XML中配置bean。

　　　　　　再经过@EnableSwagger2注解来启动Swagger2

@Configuration
public class Swagger2Config {
 
    //是否开启swagger，正式环境通常是须要关闭的，可根据springboot的多环境配置进行设置
    @Value(value = "${swagger.enabled}")
    Boolean swaggerEnabled;
 
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                // 是否开启
                .enable(swaggerEnabled).select()
                // 扫描的路径包
                .apis(RequestHandlerSelectors.basePackage("com.jack.springboot.controller"))
                // 指定路径处理PathSelectors.any()表明全部的路径
                .paths(PathSelectors.any()).build().pathMapping("/");
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot-Swagger2示例")
                .description("jacking0325")
                // 做者信息
                .contact(new Contact("jacking0325", "https://blog.jack0325.cn/", "111111111@qq.com"))
                .version("1.0.0")
                .build();
    }
}

　　3）Application.class 加上注解@EnableSwagger2 表示开启Swagger

@SpringBootApplication
@EnableSwagger2
public class SpringbootSwagger2Application {

	public static void main(String[] args) {
		SpringApplication.run(SpringbootSwagger2Application.class, args);
	}
}

　　4）RESTful接口（基础打好，开始在代码中使用）

@RestController
public class UserController {

	// 建立线程安全的Map
	static Map<Integer, User> users = Collections.synchronizedMap(new HashMap<Integer, User>());

	/**
	 * 根据ID查询用户
	 * @param id
	 * @return
	 */
	@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
	@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
	@RequestMapping(value = "user/{id}", method = RequestMethod.GET)
	public ResponseEntity<JsonResult> getUserById (@PathVariable(value = "id") Integer id){
		JsonResult r = new JsonResult();
		try {
			User user = users.get(id);
			r.setResult(user);
			r.setStatus("ok");
		} catch (Exception e) {
			r.setResult(e.getClass().getName() + ":" + e.getMessage());
			r.setStatus("error");
			e.printStackTrace();
		}
		return ResponseEntity.ok(r);
	}

	/**
	 * 查询用户列表
	 * @return
	 */
	@ApiOperation(value="获取用户列表", notes="获取用户列表")
	@RequestMapping(value = "users", method = RequestMethod.GET)
	public ResponseEntity<JsonResult> getUserList (){
		JsonResult r = new JsonResult();
		try {
			List<User> userList = new ArrayList<User>(users.values());
			r.setResult(userList);
			r.setStatus("ok");
		} catch (Exception e) {
			r.setResult(e.getClass().getName() + ":" + e.getMessage());
			r.setStatus("error");
			e.printStackTrace();
		}
		return ResponseEntity.ok(r);
	}

	/**
	 * 添加用户
	 * @param user
	 * @return
	 */
	@ApiOperation(value="建立用户", notes="根据User对象建立用户")
	@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
	@RequestMapping(value = "user", method = RequestMethod.POST)
	public ResponseEntity<JsonResult> add (@RequestBody User user){
		JsonResult r = new JsonResult();
		try {
			users.put(user.getId(), user);
			r.setResult(user.getId());
			r.setStatus("ok");
		} catch (Exception e) {
			r.setResult(e.getClass().getName() + ":" + e.getMessage());
			r.setStatus("error");

			e.printStackTrace();
		}
		return ResponseEntity.ok(r);
	}

	/**
	 * 根据id删除用户
	 * @param id
	 * @return
	 */
	@ApiOperation(value="删除用户", notes="根据url的id来指定删除用户")
	@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
	@RequestMapping(value = "user/{id}", method = RequestMethod.DELETE)
	public ResponseEntity<JsonResult> delete (@PathVariable(value = "id") Integer id){
		JsonResult r = new JsonResult();
		try {
			users.remove(id);
			r.setResult(id);
			r.setStatus("ok");
		} catch (Exception e) {
			r.setResult(e.getClass().getName() + ":" + e.getMessage());
			r.setStatus("error");

			e.printStackTrace();
		}
		return ResponseEntity.ok(r);
	}

	/**
	 * 根据id修改用户信息
	 * @param user
	 * @return
	 */
	@ApiOperation(value="更新信息", notes="根据url的id来指定更新用户信息")
	@ApiImplicitParams({
			@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",paramType = "path"),
			@ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
	})
	@RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
	public ResponseEntity<JsonResult> update (@PathVariable("id") Integer id, @RequestBody User user){
		JsonResult r = new JsonResult();
		try {
			User u = users.get(id);
			u.setUsername(user.getUsername());
			u.setAge(user.getAge());
			users.put(id, u);
			r.setResult(u);
			r.setStatus("ok");
		} catch (Exception e) {
			r.setResult(e.getClass().getName() + ":" + e.getMessage());
			r.setStatus("error");

			e.printStackTrace();
		}
		return ResponseEntity.ok(r);
	}

	@ApiIgnore//使用该注解忽略这个API
	@RequestMapping(value = "/hi", method = RequestMethod.GET)
	public String  jsonTest() {
		return " hi you!";
	}
}

　　5）Json格式输出类 JsonResult.class

public class JsonResult {

	private String status = null;

	private Object result = null;

	// Getter Setter
}

　　6）Swagger访问与使用

　　　　启动springBoot项目，访问api首页路径：http://localhost:8080/swagger-ui.html

　　　　建议在生产环境关闭Swagger2！

@RestControllerpublic class UserController { // 建立线程安全的Map static Map<Integer, User> users = Collections.synchronizedMap(new HashMap<Integer, User>()); /** * 根据ID查询用户 * @param id * @return */ @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息") @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path") @RequestMapping(value = "user/{id}", method = RequestMethod.GET) public ResponseEntity<JsonResult> getUserById (@PathVariable(value = "id") Integer id){ JsonResult r = new JsonResult(); try { User user = users.get(id); r.setResult(user); r.setStatus("ok"); } catch (Exception e) { r.setResult(e.getClass().getName() + ":" + e.getMessage()); r.setStatus("error"); e.printStackTrace(); } return ResponseEntity.ok(r); } /** * 查询用户列表 * @return */ @ApiOperation(value="获取用户列表", notes="获取用户列表") @RequestMapping(value = "users", method = RequestMethod.GET) public ResponseEntity<JsonResult> getUserList (){ JsonResult r = new JsonResult(); try { List<User> userList = new ArrayList<User>(users.values()); r.setResult(userList); r.setStatus("ok"); } catch (Exception e) { r.setResult(e.getClass().getName() + ":" + e.getMessage()); r.setStatus("error"); e.printStackTrace(); } return ResponseEntity.ok(r); } /** * 添加用户 * @param user * @return */ @ApiOperation(value="建立用户", notes="根据User对象建立用户") @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User") @RequestMapping(value = "user", method = RequestMethod.POST) public ResponseEntity<JsonResult> add (@RequestBody User user){ JsonResult r = new JsonResult(); try { users.put(user.getId(), user); r.setResult(user.getId()); r.setStatus("ok"); } catch (Exception e) { r.setResult(e.getClass().getName() + ":" + e.getMessage()); r.setStatus("error"); e.printStackTrace(); } return ResponseEntity.ok(r); } /** * 根据id删除用户 * @param id * @return */ @ApiOperation(value="删除用户", notes="根据url的id来指定删除用户") @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path") @RequestMapping(value = "user/{id}", method = RequestMethod.DELETE) public ResponseEntity<JsonResult> delete (@PathVariable(value = "id") Integer id){ JsonResult r = new JsonResult(); try { users.remove(id); r.setResult(id); r.setStatus("ok"); } catch (Exception e) { r.setResult(e.getClass().getName() + ":" + e.getMessage()); r.setStatus("error"); e.printStackTrace(); } return ResponseEntity.ok(r); } /** * 根据id修改用户信息 * @param user * @return */ @ApiOperation(value="更新信息", notes="根据url的id来指定更新用户信息") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",paramType = "path"), @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User") }) @RequestMapping(value = "user/{id}", method = RequestMethod.PUT) public ResponseEntity<JsonResult> update (@PathVariable("id") Integer id, @RequestBody User user){ JsonResult r = new JsonResult(); try { User u = users.get(id); u.setUsername(user.getUsername()); u.setAge(user.getAge()); users.put(id, u); r.setResult(u); r.setStatus("ok"); } catch (Exception e) { r.setResult(e.getClass().getName() + ":" + e.getMessage()); r.setStatus("error"); e.printStackTrace(); } return ResponseEntity.ok(r); } @ApiIgnore//使用该注解忽略这个API @RequestMapping(value = "/hi", method = RequestMethod.GET) public String jsonTest() { return " hi you!"; } }