【学习总结】使用Swagger实现API规范

【学习总结】使用Swagger实现API规范

1. 建立一个springboot工程
2. 建立实体类
3. 建立数据库并链接数据库，进行增删改查编写
4. 为工程增加swagger配置
5. 请求页面，显示结果
代码如下
1、建立工程
2、建立实体类

import io.swagger.annotations.ApiModel;
import lombok.Data;
import javax.persistence.*;
@Data
@Table(name = "classes")
@ApiModel(value = "com.lxc.swagger.entity.Classes", description = "班级字段特征")
public class Classes {
    @Id
    @Column(name = "id")
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer id;//班级编号
    private int studentNumbers;//学生人数
    private  String major;//专业
    private String college;//所属学院
}

1、建立数据库链接，这里采用的是mysql
2、进行增删改查设置，这里使用fastmybatis
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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.2.2.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.lxc</groupId>
	<artifactId>swagger</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>swagger</name>
	<description>Demo project for Spring Boot</description>

	<properties>
		<java.version>1.8</java.version>
	</properties>

	<dependencies>
		<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.projectlombok</groupId>
			<artifactId>lombok</artifactId>
			<optional>true</optional>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>net.oschina.durcframework</groupId>
			<artifactId>fastmybatis-spring-boot-starter</artifactId>
			<version>1.0.2</version>
		</dependency>
		<!-- Swagger -->
		<dependency>
			<groupId>com.spring4all</groupId>
			<artifactId>swagger-spring-boot-starter</artifactId>
			<version>1.7.1.RELEASE</version>
		</dependency>
	</dependencies>

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

</project>

数据库链接配置

spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.datasource.url=jdbc:mysql://localhost:3306/swagger?serverTimezone=UTC&useUnicode=true&characterEncoding=utf-8&zeroDateTimeBehavior=convertToNull
spring.datasource.username=root
spring.datasource.password=root

编写sql建立表格

CREATE TABLE classes(
    id INT(11) NOT NULL AUTO_INCREMENT COMMENT 'ID',
    student_numbers INT(11) DEFAULT 0 COMMENT '学生个数',
    major VARCHAR (255) DEFAULT NULL COMMENT '专业',
    college VARCHAR (255) DEFAULT NULL COMMENT '所属学院',
    PRIMARY KEY (id)
)ENGINE=INNODB AUTO_INCREMENT=7 DEFAULT CHARSET=utf8 COMMENT '班级表'

使用fastmybatis进行数据添加

package com.lxc.swagger.dao;

import com.gitee.fastmybatis.core.mapper.CrudMapper;
import com.lxc.swagger.entity.Classes;

public interface ClassesMapper extends CrudMapper<Classes,Integer> {
}

添加数据（测试类）

package com.lxc.swagger.dao;

import com.lxc.swagger.entity.Classes;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;
import org.junit.Test;
import org.junit.runner.RunWith;

@SpringBootTest
@RunWith(SpringRunner.class)
public class ClassesMapperTest {
    @Autowired ClassesMapper classesMapper;
    @Test
    public void saveClasses(){
        Classes classes=new Classes();
        classes.setId(1);
        classes.setCollege("航空航天学院");
        classes.setMajor("控制工程");
        classes.setStudentNumbers(48);
        classesMapper.save(classes); 
    }

}

在controller进行数据查询
@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”；其他参数可参考源码；
@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”

package com.lxc.swagger.controller;

import com.gitee.fastmybatis.core.query.Query;
import com.lxc.swagger.dao.ClassesMapper;
import com.lxc.swagger.entity.Classes;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
public class ClassesController {
    @Autowired
   private ClassesMapper classesMapper;
    @GetMapping("pageClasses")
    @ResponseBody
    //配置swagger的说明
    @ApiOperation(value ="根据给定的页数和页面大小来获取班级列表",httpMethod ="GET"
            ,response=Classes.class, notes="根据页面获取班级列表")
    public List<Classes> page1(int pageIndex, int pageSize) {
        Query query = new Query();
        query.page(pageIndex, pageSize);
        List<Classes> list = classesMapper.list(query);
        return list;
    }
}

4. 为工程增加swagger配置

@SpringBootApplication
@EnableSwagger2Doc//进行允许使用swagger的配置
public class SwaggerApplication {

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

}

5. 请求页面，显示结果
在浏览器输入网址http://localhost:8080/swagger-ui.html
这里的8080是我的端口号

显示界面如下

其中的classes-controller就是我相应的api
点击即可进入显示

点击try it out按钮既可输入相应的数据进行请求