使用 SpringBoot + Swagger 生成接口 API 文档

一、前言

1、这阵子要和团队萌萌的队友合作开发一些小型的项目，在下负责后台工作，界面就由安卓、前端等去搞了。

2、回想起之前的全栈式开发，现在瞬间感觉轻飘飘

3、为了更好地向负责界面的队友说明接口，swagger真的是及时雨

4、下面来点使用记录

二、代码

后台使用 SpringBoot ，修改自之前的使用 SpringBoot 写 RESTful风格 增删改查接口

1、目录

由于比较简单，省略了 service

2、entity

package com.cun.entity;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
import javax.persistence.Table;

import io.swagger.annotations.ApiModelProperty;

@Entity
@Table(name = "t_user")
public class User {

@Id
@GeneratedValue
@ApiModelProperty(value = "用户id")
private Integer id;

@Column(length = 50)
@ApiModelProperty(value = "用户名")
private String name;

@Column(length = 50)
@ApiModelProperty(value = "用户密码")
private String word;

public Integer getId() {

4000
return id;
}

public void setId(Integer id) {
this.id = id;
}

public String getName() {
return name;
}

public void setName(String name) {
this.name = name;
}

public String getWord() {
return word;
}

public void setWord(String word) {
this.word = word;
}

}

3、dao

package com.cun.dao;

import org.springframework.data.jpa.repository.JpaRepository;

import com.cun.entity.User;

public interface UserDao extends JpaRepository<User, Integer>{

}

4、controller

package com.cun.controller;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
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.PutMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.cun.dao.UserDao;
import com.cun.entity.User;

import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@RestController
@RequestMapping("/user")
@EnableSwagger2 // 让swagger生成接口文档
public class UserController {

@Autowired
private UserDao userDao;

@ApiOperation(value = "查找所有用户")
@GetMapping(value = "/all")
public List<User> findAllUser() {
return userDao.findAll();
}

@ApiOperation(value = "查找一个用户")
@GetMapping("/find/{id}")
public User findOneUser(@ApiParam(value = "用户id") @PathVariable("id") Integer id) {
return userDao.findOne(id);
}

@ApiOperation(value = "删除一个用户")
@DeleteMapping("/delete/{id}")
public void deleteUser(@ApiParam(value = "用户id") @PathVariable("id") Integer id) {
userDao.delete(id);
}

@ApiOperation(value = "新增一个用户")
@PostMapping("/add")
public void addStudentRestful(@ApiParam(value = "用户或用户各个属性") User user) {
userDao.save(user);
}

@ApiOperation(value = "更新一个用户")
@PutMapping("/update")
public void updateUser(@ApiParam(value = "用户或用户各个属性") User user) {
userDao.save(user);
}

}

5、pom

<?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"> <modelVersion>4.0.0</modelVersion>

<groupId>com.cun</groupId>
<artifactId>RestSwagger</artifactId>
<version>0.0.1-SNAPSHOT</version>
<packaging>war</packaging>

<name>RestSwagger</name>
<description>Demo project for Spring Boot</description>

<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.5.10.RELEASE</version>
<relativePath /> <!-- lookup parent from repository -->
</parent>

<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<java.version>1.8</java.version>
</properties>

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

<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>

<!-- swagger生成接口API -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>

<!-- 接口API生成html文档 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>

beaf
<version>2.6.1</version>
</dependency>

</dependencies>

<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>

</project>

6、效果

① 进入 swagger 界面：如 http://localhost/swagger-ui.html

② 整体效果：



③详细效果

三、小结

1、使用 swagger 常用的注解

① @EnableSwagger2

用于控制层，生成 API 文档的核心

② @ApiModelProperty(value = “用户id”)

用于实体层，属性有中文说明

③ @ApiParam(value = “用户id”)

用于控制层的参数

2、建议

① @RequestMapping 中的方法要声明好为 get/post/put/delete，否则API文档有很多冗余

② 建议使用 rest 风格，即使用 @GetMapping、@DeleteMapping、@PostMapping、@PutMapping 这4个取代笼统的 @RequestMapping