日志

Spring Boot 教程 (4) - swagger-ui

 来源    2020-05-23    1  

Spring Boot 教程 - swagger-ui

1. 什么是Swagger?

Swagger™的目标是为REST APIs 定义一个标准的,与语言无关的接口,使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义,消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口,Swagger去掉了调用服务时的很多猜测。
浏览 Swagger 去了解更多关于Swagger 项目的信息,包括附加的支持其他语言的库。

2. 在项目中集成Swagger

  • 2.1 引入maven依赖

    我自己的项目中使用的是swagger2。

    <!--springboot父工程-->
        <parent>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-parent</artifactId>
            <version>2.2.2.RELEASE</version>
            <relativePath/> <!-- lookup parent from repository -->
        </parent>
    
        <dependencies>
            <!--springboot框架web组件-->
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
                <version>2.2.2.RELEASE</version>
            </dependency>
            <!--swagger-ui组件-->
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.9.2</version>
            </dependency>
            <!--swagger组件-->
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.9.2</version>
            </dependency>
            <!--mybatis整合springboot组件-->
            <dependency>
                <groupId>org.mybatis.spring.boot</groupId>
                <artifactId>mybatis-spring-boot-starter</artifactId>
                <version>2.1.0</version>
            </dependency>
            <!--mysql数据库连接驱动-->
            <dependency>
                <groupId>mysql</groupId>
                <artifactId>mysql-connector-java</artifactId>
                <version>8.0.18</version>
            </dependency>
            <!--lombok组件-->
            <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>1.18.10</version>
            </dependency>
        </dependencies>
    
        <build>
            <!--springboot的maven插件-->
            <plugins>
                <plugin>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-maven-plugin</artifactId>
                </plugin>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <configuration>
                        <compilerArgs>
                            <arg>-parameters</arg>
                        </compilerArgs>
                    </configuration>
                </plugin>
            </plugins>
        </build>
  • 2.2 Swagger的配置

    SwggerConfig.java

    package com.butterflytri.config;
    
    import com.google.common.base.Predicates;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.context.annotation.Profile;
    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;
    import java.util.HashSet;
    import java.util.List;
    import java.util.Set;
    
    /**
     * @author: WJF
     * @date: 2020/5/21
     * @description: SwaggerConfig
     */
    
    /**
     * {@link Configuration}:标志这是一个配置类,在spring boot引导类启动时,会自动加载这个类的配置。
     * {@link Profile}:说明加载配置文件 'application.yml' 时加载对应的配置。
     * {@link EnableSwagger2}:启用Swagger2的配置。
     */
    @Configuration
    @Profile("dev")
    @EnableSwagger2
    public class SwaggerConfig {
    
        @Bean
        public Docket restApi() {
            Class[] classes = this.getClasses();
            Set<String> consumesSet = new HashSet<>();
            consumesSet.add("application/x-www-form-urlencoded");
            return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .globalOperationParameters(parameters())
                .ignoredParameterTypes(classes)
                .forCodeGeneration(true)
                .consumes(consumesSet)
                .select()
                .apis(Predicates.and(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)))
                .paths(PathSelectors.any())
                .build();
        }
    
        /**
         * API文档的基本信息
         * @return ApiInfo
         */
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("学生管理平台")
                    .description("学生管理平台文档")
                    .termsOfServiceUrl("http://127.0.0.1:8080/butterflytri/swagger-ui.html")
                    .contact(new Contact("wjf", "http://butterflytri.com", "butterflytri@163.com"))
                    .version("2.0")
                    .build();
        }
    
        /**
         * Swagger2可以在Swagger2文档中添加参数
         * @return List<Parameter>
         */
        private List<Parameter> parameters() {
            // 添加一个参数butterflytri,参数描述:不死蝶
            ParameterBuilder paramBuilder = new ParameterBuilder();
            List<Parameter> paramList = new ArrayList<Parameter>();
            paramBuilder.name("butterflytri")
                    .description("不死蝶")
                    .modelRef(new ModelRef("string"))
                    .parameterType("header")
                    .required(true)
                    .build();
            paramList.add(paramBuilder.build());
            return paramList;
        }
    
    
        /**
         * 获取class数组
         * @return Class[]
         */
        private Class[] getClasses() {
            return new Class[]{};
        }
    
    }
  • 2.3 控制层

    StudentController.java

    package com.butterflytri.controller;
    
    import com.butterflytri.entity.Student;
    import com.butterflytri.service.StudentService;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiImplicitParams;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.web.bind.annotation.*;
    
    import javax.annotation.Resource;
    import java.util.List;
    
    /**
     * @author: WJF
     * @date: 2020/5/16
     * @description: StudentController
     */
    @Api(tags = "学生管理接口")
    @RestController
    @RequestMapping("/student")
    public class StudentController {
    
        @Resource
        private StudentService studentService;
    
        /**
         * GET :请求从服务器获取特定资源。举个例子:GET /student(获取所有学生)
         * @return List<Student>
         */
        @ApiOperation(value = "查询所有学生", httpMethod = "GET", notes = "查询所有学生")
        @GetMapping("/student")
        public List<Student> student() {
            return studentService.findAll();
        }
    
        /**
         * GET :请求从服务器获取特定资源。举个例子:GET /student/1(获取id为1学生)
         * @param id
         * @return Student
         */
        @ApiOperation(value = "查询学生详情", httpMethod = "GET", notes = "查询学生详情")
        @ApiImplicitParam(name = "id", value = "学生id", required = true, paramType = "form", dataTypeClass = Long.class)
        @GetMapping("/student/{id}")
        public Student student(@PathVariable("id") Long id) {
            return studentService.findOne(id);
        }
    
        /**
         * POST :在服务器上创建一个新的资源。举个例子:POST /student(添加学生)
         * @param student
         */
        @PostMapping("/student")
        @ApiOperation(value = "添加学生", httpMethod = "POST", notes = "添加学生")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "studentName", value = "学生姓名", required = true, paramType = "form", dataTypeClass = String.class),
                @ApiImplicitParam(name = "studentNo", value = "学生学号", required = true, paramType = "form", dataTypeClass = String.class),
                @ApiImplicitParam(name = "sex", value = "学生性别", required = true, paramType = "form", dataTypeClass = String.class),
                @ApiImplicitParam(name = "age", value = "学生年龄", required = true, paramType = "form", dataTypeClass = Integer.class)
        })
        public void student(@RequestBody Student student) {
            studentService.add(student);
        }
    
        /**
         * PUT :更新服务器上的资源(客户端提供更新后的整个资源)。举个例子:PUT /student/1(更新学号为 1 的学生的所有信息)
         * @param id
         */
        @PutMapping("/student/{id}")
        @ApiOperation(value = "根据id修改学生信息(大范围)", httpMethod = "PUT", notes = "根据id修改学生信息")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "id", value = "学生id", required = true, paramType = "from", dataTypeClass = Long.class),
                @ApiImplicitParam(name = "studentName", value = "学生姓名", required = true, paramType = "form", dataTypeClass = String.class),
                @ApiImplicitParam(name = "studentNo", value = "学生学号", required = true, paramType = "form", dataTypeClass = String.class),
                @ApiImplicitParam(name = "sex", value = "学生性别", required = true, paramType = "form", dataTypeClass = String.class),
                @ApiImplicitParam(name = "age", value = "学生年龄", required = true, paramType = "form", dataTypeClass = Integer.class)
        })
        public void updateById(@PathVariable("id") Long id, Student student) {
            studentService.updateAll(id,student);
        }
    
        /**
         * DELETE :从服务器删除特定的资源。举个例子:DELETE /student/1(删除学号为 1 的学生)
         * @param id
         */
        @DeleteMapping("/student/{id}")
        @ApiOperation(value = "根据id删除学生信息", httpMethod = "DELETE", notes = "根据id删除学生信息")
        @ApiImplicitParam(name = "id", value = "学生id", required = true, paramType = "from", dataTypeClass = Long.class)
        public void deleteById(@PathVariable("id") Long id) {
            studentService.delete(id);
        }
    
        /**
         * PATCH :更新服务器上的资源(客户端提供更改的属性,可以看做作是部分更新),使用的比较少,这里就不举例子了。
         * @param id
         * @param student
         */
        @PatchMapping("/student/{id}")
        @ApiOperation(value = "根据id修改学生信息(小范围)", httpMethod = "PATCH", notes = "根据id修改学生信息")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "id", value = "学生id", required = true, paramType = "from", dataTypeClass = Long.class),
                @ApiImplicitParam(name = "studentName", value = "学生姓名", required = true, paramType = "form", dataTypeClass = String.class),
                @ApiImplicitParam(name = "studentNo", value = "学生学号", required = true, paramType = "form", dataTypeClass = String.class),
                @ApiImplicitParam(name = "sex", value = "学生性别", required = true, paramType = "form", dataTypeClass = String.class),
                @ApiImplicitParam(name = "age", value = "学生年龄", required = true, paramType = "form", dataTypeClass = Integer.class)
        })
        public void updatePart(@PathVariable("id") Long id, Student student) {
            studentService.updatePart(id,student);
        }
    
    }

    这些注解也是很容易理解的,相信各位聪明的技术大牛很快就会使用了。这些注解的具体作用其实看看就懂了,甚至不用去查资料,在这里解释下@ApiImplicitParam这个注解的一个属性paramType,这个属性的取值有以下几种:

    • header:放在请求头,用于请求头参数的获取。使用@RequestHeader,在代码中接收参数。
    • query:用于get请求的参数拼接。使用@RequestParam,在代码中接收参数。
    • path:用于restful接口请求参数的获取。使用@PathVariable,在映射地址上接收参数。
    • body:放在请求体中,使用@RequestBody接收参数。
    • form:使用form表单的形式传递参数。
  • 2.4 Entity

    Student.java

    package com.butterflytri.entity;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Getter;
    import lombok.Setter;
    import lombok.ToString;
    
    import java.io.Serializable;
    
    /**
     * @author: WJF
     * @date: 2020/5/16
     * @description: Student
     */
    
    @ToString
    @Getter
    @Setter
    @ApiModel("学生Entity")
    public class Student implements Serializable {
    
        @ApiModelProperty("学生id")
        private Long id;
    
        @ApiModelProperty("学生姓名")
        private String studentName;
    
        @ApiModelProperty("学生学号")
        private String studentNo;
    
        @ApiModelProperty("性别")
        private String sex;
    
        @ApiModelProperty("年龄")
        private Integer age;
    
    }

    可以使用@ApiModelProperty注解来标识每个Entity属性的意思。

  • 2.5 运行结果

    启动项目,访问http://127.0.0.1:8080/butterflytri/swagger-ui.html即可看到下面的页面:

    点开学生管理接口可以看到StudentController.java中写的所有接口方法:

    点开下面的Models,可以看到Entity中的Student.java实体类:

    再点开查询所有学生这个方法,调用一下这个方法,点击Try it out测试一下方法:

    在这里看到了一个参数butterflytri,而且还是必传参数,这是因为我在SwaggerConfig.java这个配置文件类中进行了配置,不清楚的可以往上翻一翻,看看那个配置类。

    点击了Try it out按钮后,随便给这个参数赋值,反正这个参数没有什么,只是给大家做演示看的。然后点击execute按钮,就可以看到返回结果:

3. 项目地址

本项目传送门:spring-boot-swagger-ui

此教程会一直更新下去,觉得博主写的可以的话,关注一下,也可以更方便下次来学习。

相关文章
Spring Boot&&Spring Cloud系列 Spring Boot项目集成Swagger UI
日志前言 Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参数和模型紧密集 ...
1
Spring Boot 2.0 教程 | 快速集成整合消息中间件 Kafka
日志欢迎关注个人微信公众号: 小哈学Java, 每日推送 Java 领域干货文章,关注即免费无套路附送 100G 海量学习.面试资源哟!! 个人网站: https://www.exception.site ...
1
Spring boot教程
日志1.首先是新建Maven工程 2.引入Pom依赖 3.新建一个Controller 4.运行Main方法 5.浏览器访问 pom.xml <project xmlns="http:// ...
程序员DD 《Spring boot教程系列》补充
日志最近在跟着程序员DD的Spring boot教程系列学习Spring boot,由于年代原因,Spring boot已经发生了一些变化,所以在这里进行一些补充. 补充的知识大多来自评论区,百度,Sta ...
Spring Boot:整合Swagger文档
日志综合概述 spring-boot作为当前最为流行的Java web开发脚手架,越来越多的开发者选择用其来构建企业级的RESTFul API接口.这些接口不但会服务于传统的web端(b/s),也会服务于 ...
spring boot 中使用swagger 来自动生成接口文档
日志1.依赖包 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swa ...
SpringBoot整合Quartz定时任务 系统job Spring Boot教程 调度任务
日志原文地址:https://www.cnblogs.com/allalongx/p/8477368.html 构建工程 创建一个Springboot工程,在它的程序入口加上@EnableScheduli ...
Spring Boot 2.0 教程 | @ModelAttribute 注解
日志欢迎关注微信公众号: 小哈学Java 文章首发于个人网站: https://www.exception.site/springboot/spring-boot-model-attribute Spri ...
Spring Boot 2.0 教程 | 配置 Undertow 容器
日志欢迎关注个人微信公众号: 小哈学Java, 文末分享阿里 P8 资深架构师吐血总结的 <Java 核心知识整理&面试.pdf>资源链接!! 文章首发于个人网站 https://ww ...
1
Spring Boot 2.0 教程 | AOP 切面统一打印请求日志
日志欢迎关注微信公众号: 小哈学Java 文章首发于个人网站 https://www.exception.site/springboot/spring-boot-aop-web-request 本节中,您 ...
Spring boot 下使用 Swagger
日志通过Swagger 可以更好的将后台的RESTfull API文档化,如下图所示: 1. Swagger 主要依赖以下两个jar包: <!-- https://mvnrepository.com ...
1
Spring Boot 教程
日志Spring boot是一个Spring框架模块,它为Spring框架提供RAD(快速应用程序开发)功能.它高度依赖于启动器模板功能,该功能非常强大且完美无缺. ###1.什么是Spring boot ...
Spring Boot 2.0 教程 - 配置详解
日志Spring Boot 可以通过properties文件,YAML文件,环境变量和命令行参数进行配置.属性值可以通过,@Value注解,Environment或者ConfigurationProper ...
1
Spring Boot 2.0 教程 - 深入SpringAplication
日志原文连接:https://www.codemore.top/cates/Backend/post/2018-05-20/spring-boot-SpringApplication 可以通过Spring ...
Spring Boot教程(七)通过springboot 去创建和提交一个表单
日志创建工程 涉及了 web,加上spring-boot-starter-web和spring-boot-starter-thymeleaf的起步依赖. <dependencies> < ...
Spring Boot教程(一)在springboot中用redis实现消息队列
日志环境依赖 创建一个新的springboot工程,在其pom文件,加入spring-boot-starter-data-redis依赖: <dependency> <groupId&g ...
1
Spring Boot教程(十一) springboot程序构建一个docker镜像
日志准备工作 环境: linux环境或mac,不要用windows jdk 8 maven 3.0 docker 对docker一无所知的看docker教程. 创建一个springboot工程 引入web ...
Spring Boot教程(四十二)LDAP来管理用户信息(2)
日志使用spring-data-ldap的基础用法,定义LDAP中属性与我们Java中定义实体的关系映射以及对应的Repository @Data @Entry(base = "ou=peopl ...
1
Spring Boot教程(四十一)LDAP来管理用户信息(1)
日志LDAP简介 LDAP(轻量级目录访问协议,Lightweight Directory Access Protocol)是实现提供被称为目录服务的信息服务.目录服务是一种特殊的数据库系统,其专门针对读 ...
1
Spring Boot教程(四十)使用Flyway来管理数据库版本
日志在上面的使用JdbcTemplate一文中,主要通过spring提供的JdbcTemplate实现对用户表的增删改查操作.在实现这个例子的时候,我们事先在MySQL中创建了用户表.创建表的过程我们在实 ...
2