Spring Boot2.0系列教程之Swagger 生成接口 API 文档（九）

什么是swagger？

Swagger 是最流行的 API 开发工具，它遵循 OpenAPI Specification（OpenAPI 规范，也简称 OAS）。

Swagger 可以贯穿于整个 API 生态，如 API 的设计、编写 API 文档、测试和部署。

Swagger 是一种通用的，和编程语言无关的 API 描述规范。

应用场景

• 如果你的 RESTful API 接口都开发完成了，你可以用 Swagger-editor 来编写 API 文档（ yaml 文件 或 json 文件），然后通过 Swagger-ui 来渲染该文件，以非常美观的形式将你的 API 文档，展现给你的团队或者客户。
• 如果你的 RESTful API 还未开始，也可以使用 Swagger 生态，来设计和规范你的 API，以 Annotation （注解）的方式给你的源代码添加额外的元数据。这样，Swagger 就可以检测到这些元数据，自动生成对应的 API 描述信息。也就是说，Swagger 支持自动生成 API 文档。

注：第一部分为代码，第二部分为演示swagger生成接口后操作的截图，完整代码可在github下载。

github地址：https://github.com/zjh746140129/Spring-Boot2.0

项目结构截图：

 

一、代码片段

1、编写用户类

package com.boot.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;

/**
 * Created by zhoujh on 2018/7/20.
 */
@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;
    }
}

2、编写接口

package com.boot.repository;

import com.boot.entity.User;
import org.springframework.data.jpa.repository.JpaRepository;

/**
 * Created by zhoujh on 2018/7/20.
 */
public interface UserDao extends JpaRepository<User, Integer> {
}

3、编写controller

package com.boot.controller;


import java.util.List;

import com.boot.entity.User;
import com.boot.repository.UserDao;
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 io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Created by zhoujh on 2018/7/20.
 */

@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.getOne(id);
    }

    @ApiOperation(value = "删除一个用户")
    @DeleteMapping("/delete/{id}")
    public void deleteUser(@ApiParam(value = "用户id") @PathVariable("id") Integer id) {
        userDao.deleteById(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);
    }
}

4、启动类

package com.boot;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class BootSwaggerApplication {

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

5、配置文件

spring.datasource.url=jdbc:mysql://localhost:3306/school_score
spring.datasource.username=root
spring.datasource.password=root
spring.datasource.driver-class-name=com.mysql.jdbc.Driver

spring.jpa.properties.hibernate.hbm2ddl.auto=update
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
spring.jpa.show-sql= true
server.port=8099

6、完整pom.xml

<?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.boot</groupId>
	<artifactId>boot-swagger</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>jar</packaging>

	<name>boot-swagger</name>
	<description>Demo project for Spring Boot</description>

	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.0.3.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>org.springframework.boot</groupId>
			<artifactId>spring-boot-devtools</artifactId>
			<scope>runtime</scope>
		</dependency>
		<dependency>
			<groupId>mysql</groupId>
			<artifactId>mysql-connector-java</artifactId>
			<scope>runtime</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>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
	</dependencies>

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


</project>

 

二、演示swagger

1、访问swagger，http://localhost:8099/swagger-ui.html

 

2、使用接口测试新增用户

 

3、使用接口测试查询

 

好了，到这里 Spring Boot2.0系列教程之Swagger 生成接口 API 文档就完成了，读者在实践过程中有问题，评论私信即可，回第一时间回复。