springboot集成Swagger
Swagger是一个用于生成RESTful 风格的api的框架,可以减少开发人员写文档的时间,简单实用,下面开始介绍怎么在springboot中使用它
1创建springboot初始项目
这里要选中web模块
这是创建出来的项目结构
2添加依赖
在pom里面添加Swagger依赖
<!--swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
如下图
点击右下角会帮你自动导入
3配置Swagger
新建一个Swaggerconfig作为Swagger的配置类
添加如下代码
package com.demo.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
@EnableSwagger2
@Configuration
public class SwaggerConfig {
@Bean
public Docket Lamp() {
Parameter token = new ParameterBuilder().name("token") //全局参数
.description("用户登陆令牌")
.parameterType("header")
.modelRef(new ModelRef("String"))
.required(true)
.build();
ArrayList<Parameter> parameters = new ArrayList<>();
parameters.add(token);
return new Docket(DocumentationType.SWAGGER_2)
.globalOperationParameters(parameters)
.apiInfo(apiInfo())
.groupName("班级模块")
.select()
.apis(RequestHandlerSelectors.basePackage("com.demo.swagger.controller")) //根据包来扫描,也可以根据类或者方法
.paths(PathSelectors.ant("/classes/**")) //过滤不属于/classes/**的请求
.build();
}
@Bean
public Docket LampState() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.groupName("年级模块")
.select()
.apis(RequestHandlerSelectors.basePackage("com.demo.swagger.controller"))
.paths(PathSelectors.ant("/grade/**"))
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("我的SwaggerAPI")
.description("这里写文档基本信息")
// 作者信息
.contact(new Contact("总有刁民想害朕", "https://blog.youkuaiyun.com/qq_41595149", "2256222053@qq.com"))
.version("1.0.0")
.build();
}
}
这里我用Easycode自动生成了两个简单的controller,service,dao,model来作为演示,具体如何生成可以查看我上一篇文章
到这里就可以通过这个链接来查看一个初级的api了(http://127.0.0.1:8080/swagger-ui.html)
下面简单介绍一下上面的配置信息
@EnableSwagger2 :开启Swagger,这是必不可少的东西
@Configuration :表明这是一个配置类
.description(“用户登陆令牌”) //注解
.parameterType(“header”) //这个参数在什么位置
.modelRef(new ModelRef(“String”))//这个参数的类型
.required(true) //这个参数是否必填
globalOperationParameters(parameters):用来添加全局参数的
.groupName(“班级模块”):指定模块名也就是下面这个地方要显示的
.title(“我的SwaggerAPI”)
.description(“这里写文档基本信息”)
// 作者信息
.contact(new Contact(“总有刁民想害朕”, “https://blog.youkuaiyun.com/qq_41595149”, "2256222053@qq.com"))
.version(“1.0.0”)
这里对应的就是下面这里
4,下面开始配置controller
package com.demo.swagger.controller;
import com.demo.swagger.entity.Classes;
import com.demo.swagger.service.ClassesService;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import javax.annotation.Resource;
/**
* (Classes)表控制层
*
* @author makejava
* @since 2019-05-10 19:33:06
*/
@Api(description = "班级API")
@RestController
@RequestMapping("/classes")
public class ClassesController {
/**
* 服务对象
*/
@Resource
private ClassesService classesService;
/**
* 通过主键查询单条数据
*
* @param id 主键
* @return 单条数据
*/
@ApiOperation(value = "获取班级信息",notes = "根据ID获取班级的基本信息")
@ApiImplicitParams({
@ApiImplicitParam(paramType = "query",name = "id",dataType = "String",required = true,value = "班级id")
})
@ApiResponses({
@ApiResponse(code = 200,message = "成功"),
@ApiResponse(code=400,message = "参数不正确"),
@ApiResponse(code = 404,message = "请求路径不正确")
})
@GetMapping("/selectOne")
public Classes selectOne(Integer id) {
return this.classesService.queryById(id);
}
}
配置完成再次访问http://127.0.0.1:8080/swagger-ui.html 可以看到如下信息
@Api(description = “班级API”) : 接口头信息
@ApiImplicitParam(paramType = “query”,name = “id”,dataType = “String”,required = true,value = “班级id”):参数描述
@ApiResponses({
@ApiResponse(code = 200,message = “成功”),
@ApiResponse(code=400,message = “参数不正确”),
@ApiResponse(code = 404,message = “请求路径不正确”)
}) :返回信息描述
5配置model
package com.demo.swagger.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;
/**
* (Classes)实体类
*
* @author makejava
* @since 2019-05-10 19:33:06
*/
@ApiModel(value = "班级的实体")
public class Classes implements Serializable {
private static final long serialVersionUID = -19321030595356813L;
public Classes(){}
public Classes(Integer classesid){
this.classesid = classesid;
}
@ApiModelProperty(value = "班级id")
private Integer classesid;
@ApiModelProperty(value = "年级信息")
private Grade grade;
@ApiModelProperty(value = "班级")
private Integer classes;
public Integer getClassesid() {
return classesid;
}
public void setClassesid(Integer classesid) {
this.classesid = classesid;
}
public Grade getGrade() {
return grade;
}
public void setGrade(Grade grade) {
this.grade = grade;
}
public Integer getClasses() {
return classes;
}
public void setClasses(Integer classes) {
this.classes = classes;
}
}
@ApiModel(value = “班级的实体”) :类的注解
@ApiModelProperty(value = “班级id”):属性注解