springboot集成Swagger

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”)：属性注解

到此就结束了，最后给Swagger编写者点赞一下，真的简单而实用，如果想要更加详细的了解，参加这里

Swagger官网