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

80 阅读 0 评论 53 点赞

我是靠谱客的博主动听大侠，最近开发中收集的这篇文章主要介绍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>