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 {
}

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 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

	4.0.0

	com.boot
	boot-swagger
	0.0.1-SNAPSHOT
	jar

	boot-swagger
	Demo project for Spring Boot

	
		org.springframework.boot
		spring-boot-starter-parent
		2.0.3.RELEASE
		 
	

	
		UTF-8
		UTF-8
		1.8
	

	
		
			org.springframework.boot
			spring-boot-starter-data-jpa
		
		
			org.springframework.boot
			spring-boot-starter-thymeleaf
		
		
			org.springframework.boot
			spring-boot-starter-web
		

		
			org.springframework.boot
			spring-boot-devtools
			runtime
		
		
			mysql
			mysql-connector-java
			runtime
		

		
		
			io.springfox
			springfox-swagger2
			2.7.0
		

		
		
			io.springfox
			springfox-swagger-ui
			2.6.1
		
		
			org.springframework.boot
			spring-boot-starter-test
			test
		
	

	
		
			
				org.springframework.boot
				spring-boot-maven-plugin
			
		
	

 

二、演示swagger

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

 

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

 

3、使用接口测试查询

 

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