使用 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() {
        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>
            <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 常用的注解

@xx	ps
@EnableSwagger2	用于 controller 控制层，生成 API 文档的核心
@ApiModelProperty(value = “用户id”)	用于 bean 实体层，属性有中文说明
@ApiParam(value = “用户id”)	用于controller 控制层的方法的参数

2、建议

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

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