Swagger2介绍及在Springboot上的使用

SpringBoot上部署Swagger2

一.Swagger2是什么?

网上这么说:Swagger是一个规范和完整的框架,用于生成,描述,调用和可视化RESTful风格的Web.总目标是作为服务器以同样的速度来更新(但似乎目前实现的还不太好).文件的方法,参数和模型紧密集成到服务器端的代码,允许API来使用保持同步.Swagger让部署管理和使用功能强大的API简单起来.

我的理解:在SpringBoot每增加一个方法或几个方法都需要使用网页或者postman测试一下,同时也需要记住方法的参数/名字等内容,操作起来不是很方便.而Swagger的出现就很好的解决了这些问题,带来了很大的便利.

那么下面将Swagger2部署到SpringBoot项目中吧!

二.Swagger2在Spring Boot上部署

1.引入依赖

compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

2.在根目录下生成Swagger2类

package pers.lansir.swagger2demo00;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

// 让Spring来加载本配置
@Configuration
// 启用Swagger
@EnableSwagger2
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).select()
                // 指定扫描的包结构
                .apis(RequestHandlerSelectors.basePackage("pers.lansir.swagger2demo00"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 你的文档标题
                .title("Swagger2文档生成使用")
                // 你的描述
                .description("对接文档,查看方法")
                // 服务条款的网址
                .termsOfServiceUrl("http://www.baidu.com/about/about.html")
                // 联系信息
                .contact(//
                        new Contact("LanSir",// 你的姓名
                                "http://www.baidu.com", // 你的网址
                                "helloworldlgr@gmail.com"))// 你的邮箱
                // 文档版本
                .version("1.0")
                .build();
    }

}

3.在controller层的类中打上Swagger2标签

如下:

package pers.lansir.swagger2demo00.controller;

/*-----------------Go,My Program----------------*/
/*
 *   @Project:    swagger2demo00
 *   @Package:    pers.lansir.swagger2demo00.controller
 *   @Author :     LanSir
 *   @Email:       helloworldlgr@gmail.com
 *   @Time :       2018/10/11 15:38
 *   @Description :
 */

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import pers.lansir.swagger2demo00.bean.User;
import pers.lansir.swagger2demo00.service.UserService;

import java.util.List;

@RestController
@Api(tags = "用户相关操作")
public class UserController {

    @Autowired
    private UserService userService;

    @PostMapping("/save")
    @ApiOperation(value = "添加用户")
    public String save(User user){
        userService.save(user);
        return "保存成功";
    }

    @PutMapping("/update")
    @ApiOperation(value = "更新用户信息")
    public String update(User user){
        userService.save(user);
        return "更新成功";
    }

    @GetMapping("/findAll")
    @ApiOperation(value = "查找所有用于")
    public String findAll(){
        List<User> users = userService.findAll();
        return "查找所有";
    }

    @GetMapping("/findById")
    @ApiOperation(value = "查找单个用户")
    public String findById(Integer id){
        userService.findById(id);
        return "查找一个";
    }

    @DeleteMapping("/delete")
    @ApiOperation(value = "删除用户信息")
    public String delete(Integer id){
        userService.delete(id);
        return "删除成功";
    }
}

好了,这样就部署完成了,启动程序后,就可以访问http://localhost:8080/swagger-ui.html查看了!

效果展示:

Swagger首页.PNG
接口详情.PNG

三.Swagger的2个常用注解简单介绍

1.API

@API(tags = "订单相关操作")//给Controller类起名字,在页面上可以清楚分辨

2.@ApiOperation

@ApiOperation(value = "根据id查找用户信息")//给每个方法起个名字,轻易的就可以知道该方法的作用

附上官网:https://swagger.io/