SpringBoot2.0 整合 Swagger2 ,构建接口管理界面

一、swagger2简介

1、swagger2优点

整合到spring boot中，构建强大restful api文档。省去接口文档管理工作，修改代码，自动更新，swagger2也提供了强大的页面测试功能来调试restful api。

2、swagger2常用注解

api：修饰整个类，描述controller的作用
apioperation：描述一个类的一个方法，或者说一个接口
apiparam：单个参数描述
apimodel：用对象来接收参数
apiproperty：用对象接收参数时，描述对象的一个字段
apiresponse：http响应其中1个描述
apiresponses：http响应整体描述
apiignore：使用该注解忽略这个api
apierror ：发生错误返回的信息
apiimplicitparam：一个请求参数
apiimplicitparams：多个请求参数

二、与springboot2.0 整合

1、核心依赖

spring-boot：2.1.3.release
swagger：2.6.1

2、swagger2 配置

import org.springframework.context.annotation.bean;
import org.springframework.context.annotation.configuration;
import springfox.documentation.builders.apiinfobuilder;
import springfox.documentation.builders.pathselectors;
import springfox.documentation.builders.requesthandlerselectors;
import springfox.documentation.service.apiinfo;
import springfox.documentation.spi.documentationtype;
import springfox.documentation.spring.web.plugins.docket;
/**
 * swagger 配置文件
 */
@configuration
public class swaggerconfig {
    @bean
    public docket createrestapi() {
        return new docket(documentationtype.swagger_2)
                .apiinfo(apiinfo())
                .select()
                .apis(requesthandlerselectors.basepackage("com.swagger.two"))
                .paths(pathselectors.any())
                .build();
    }
    private apiinfo apiinfo() {
        return new apiinfobuilder()
                .title("springboot利用swagger构建api文档")
                .description("使用restful风格, 创建人：知了一笑")
                .termsofserviceurl("https://github.com/cicadasmile")
                .version("version 1.0")
                .build();
    }
}

3、启动类添加注解

@enableswagger2
@springbootapplication
public class swaggerapplication {
    public static void main(string[] args) {
        springapplication.run(swaggerapplication.class,args) ;
    }
}

4、启动效果图

三、增删改查案例

1、添加用户

(1)、代码块

@apioperation(value="添加用户", notes="创建新用户")
@apiimplicitparam(name = "user", value = "用户详细实体user", required = true, datatype = "user")
@requestmapping(value = "/adduser", method = requestmethod.post)
public responseentity<jsonresult> adduser (@requestbody user user){
    jsonresult result = new jsonresult();
    try {
        users.put(user.getid(), user);
        result.setresult(user.getid());
        result.setstatus("ok");
    } catch (exception e) {
        result.setresult("服务异常");
        result.setstatus("500");
        e.printstacktrace();
    }
    return responseentity.ok(result);
}

(2)、效果图

2、用户列表

(1)、代码块

@apioperation(value="用户列表", notes="查询用户列表")
@requestmapping(value = "/getuserlist", method = requestmethod.get)
public responseentity<jsonresult> getuserlist (){
    jsonresult result = new jsonresult();
    try {
        list<user> userlist = new arraylist<>(users.values());
        result.setresult(userlist);
        result.setstatus("200");
    } catch (exception e) {
        result.setresult("服务异常");
        result.setstatus("500");
        e.printstacktrace();
    }
    return responseentity.ok(result);
}

(2)、效果图

3、用户查询

(1)、代码块

@apioperation(value="用户查询", notes="根据id查询用户")
@apiimplicitparam(name = "id", value = "用户id", required = true, datatype = "integer", paramtype = "path")
@requestmapping(value = "/getuserbyid/{id}", method = requestmethod.get)
public responseentity<jsonresult> getuserbyid (@pathvariable(value = "id") integer id){
    jsonresult result = new jsonresult();
    try {
        user user = users.get(id);
        result.setresult(user);
        result.setstatus("200");
    } catch (exception e) {
        result.setresult("服务异常");
        result.setstatus("500");
        e.printstacktrace();
    }
    return responseentity.ok(result);
}

(2)、效果图

4、更新用户

(1)、代码块

@apioperation(value="更新用户", notes="根据id更新用户信息")
@apiimplicitparams({
        @apiimplicitparam(name = "id", value = "用户id", required = true, datatype = "long",paramtype = "path"),
        @apiimplicitparam(name = "user", value = "用户对象user", required = true, datatype = "user")
})
@requestmapping(value = "/updatebyid/{id}", method = requestmethod.put)
public responseentity<jsonresult> updatebyid (@pathvariable("id") integer id, @requestbody user user){
    jsonresult result = new jsonresult();
    try {
        user user1 = users.get(id);
        user1.setusername(user.getusername());
        user1.setage(user.getage());
        users.put(id, user1);
        result.setresult(user1);
        result.setstatus("ok");
    } catch (exception e) {
        result.setresult("服务异常");
        result.setstatus("500");
        e.printstacktrace();
    }
    return responseentity.ok(result);
}

(2)、效果图

5、删除用户

(1)、代码块

@apioperation(value="删除用户", notes="根据id删除指定用户")
@apiimplicitparam(name = "id", value = "用户id", required = true, datatype = "long", paramtype = "path")
@requestmapping(value = "/deletebyid/{id}", method = requestmethod.delete)
public responseentity<jsonresult> deletebyid (@pathvariable(value = "id") integer id){
    jsonresult result = new jsonresult();
    try {
        users.remove(id);
        result.setresult(id);
        result.setstatus("ok");
    } catch (exception e) {
        result.setresult("服务异常");
        result.setstatus("500");
        e.printstacktrace();
    }
    return responseentity.ok(result);
}

(2)、效果图

四、源代码

github：知了一笑
https://github.com/cicadasmile/middle-ware-parent