springboog整合swagger2 实现便捷高效的接口文档

1：引入依赖

        <!--swagger2依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>

        <!--swagger2-ui依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

2：swagger2配置类

@EnableSwagger2
@Configuration
public class Swagger2Config {
    @Bean
    public Docket creatRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()) //用于创建api的基本信息
                .select()   // 创建一个构造器 定义那些控制器生成的文档中包含哪些方法
                .apis(RequestHandlerSelectors.basePackage("cloud.xingzhe.springbootswagger2.controller")) // 用于定义包含那些控制器
                .paths(PathSelectors.any()) // 用于url是否可以被映射到控制器中显示文档
                .build();
    }
    private ApiInfo apiInfo(){
        Contact contact=new Contact("行者蚊子", //作者名称
                "https://blog.csdn.net/qq_39290878", //swagger点击Terms of service 的跳转地址
                "email地址");  //email
        return new ApiInfoBuilder()
                .title("行者蚊子Swagger2标题")
                .description("Swagger2测试描述")
                .contact(contact)
                .version("1.0")
                .build();
    }

}

搭建完成 可以直接访问地址 ：http://localhost:8080/swagger-ui.html

3：swagger2常用api

3.1: 配置类的注解 在代码中已详细标注

3.2：swagger2 常用注解及应用

3.2.1 swage类注解
@Api 代表是一个swagger2的资源
3.2.2 swagger2 方法注解
@ApiOperation 用于方法中 代表一个请求操作
3.2.3 swagger2 方法接受的参数注解
@ApiImplicitParams 包含多个@ApiImplicitParam
@ApiImplicitParam 代表单独的请求参数 描述请求的对象
@ApiModel 用于封装请求的对象中或放回对象中
@ApiModelProperty 用户@ApiModel类中的属性 描述
3.2.3 swagger2 方法放回的参数注解
@ApiModel 用于封装请求的对象中或放回对象中
@ApiModelProperty 用户@ApiModel类中的属性 描述

4 代码演示

package cloud.xingzhe.springbootswagger2.controller;

import cloud.xingzhe.springbootswagger2.model.dto.SysUserDTO;
import cloud.xingzhe.springbootswagger2.model.query.SysUserQuery;
import cloud.xingzhe.springbootswagger2.model.vo.SysUserVO;
import io.swagger.annotations.*;
import org.springframework.beans.BeanUtils;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(value = "用户接口列表value",tags = "用户接口列表tags")
public class SysUserController {
    @ApiOperation(value = "创建用户")
    @RequestMapping(value = "/create",method = RequestMethod.POST)
    public SysUserDTO create(SysUserDTO sysUserDTO){
        return sysUserDTO;
    }

    @ApiOperation(value = "获取用户信息")
    @ApiImplicitParams({
           @ApiImplicitParam(value = "id",name = "id"),
            @ApiImplicitParam(value = "名称",name = "name")
    })
    @RequestMapping(value = "/get",method = RequestMethod.GET)
    public SysUserVO get(String id,String name){
        SysUserVO sysUserVO=new SysUserVO();
        sysUserVO.setId(id);
        sysUserVO.setName(name);
        sysUserVO.setAddress("广东");
        sysUserVO.setAge(20);
        sysUserVO.setPassword("123456");
        return sysUserVO;
    }
    @ApiOperation(value = "根据对象进行查询")
    @RequestMapping(value = "/getBySysUserQuery",method = RequestMethod.GET)
    public SysUserVO getBySysUserQuery(SysUserQuery sysUserQuery){
        SysUserVO sysUserVO = new SysUserVO();
        BeanUtils.copyProperties(sysUserQuery,sysUserVO);
        return sysUserVO;
    }
}

@Api(value = “用户接口列表value”,tags = “用户接口列表tags”)
value,tags都为描述的意思 同时存在会被 tags覆盖

@ApiOperation(value = “创建用户”)
value 描述

@ApiOperation(value = “获取用户信息”)
@ApiImplicitParams({
@ApiImplicitParam(value = “id”,name = “id”),
@ApiImplicitParam(value = “名称”,name = “name”)
})
value 描述 name 参数

@ApiModel(value = "用户查询类")
public class SysUserQuery {
    private String id;
    @ApiModelProperty(value = "名称")
    private String name;
    @ApiModelProperty(value = "密码")
    private String password;
    @ApiModelProperty(value = "年龄",required = true)
    private Integer age;
    @ApiModelProperty(value = "地址")
    private String address;

    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }
}

@ApiModel(value = “用户查询类”) value描述
@ApiModelProperty(value = “年龄”,required = true) value描述 required 是否必传

@ApiModel(value = "用户详情")
public class SysUserVO {
    private String id;
    @ApiModelProperty(value = "名称")
    private String name;
    @ApiModelProperty(value = "密码")
    private String password;
    @ApiModelProperty(value = "年龄")
    private Integer age;
    @ApiModelProperty(value = "地址")
    private String address;

    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }
}

@ApiModel(value = “用户详情”) value 描述
@ApiModelProperty(value = “地址”) value 描述

5：源码地址
https://github.com/xingzhewenzi/springboot-examples.git
以上是springboot整合swagger2 实现便捷高效的接口文档 的教程 刚刚开始写文章 有什么需要改进的欢迎大家评论