1. 技术文章
  2. SpringBoot集成swagger

SpringBoot集成swagger

由 百般思念 提交于 2019-12-22 05:05:09

什么是swagger（了解请跳过，后面有集成的详细步骤）

Swagger介绍

前后端分离概念

我们要了解swagger，我们就要先从前后端分离去入手。按照现在的发展趋势，可以说前后端分离已经是业内对开发和部署方式所达成的一种共识。但是还有很多公司还是采用传统的开发风格，也就是以后端的MVC为主，前端人员只要提供一些静态的HTML页面、JS、CSS、Image等，然后大部分的后端团队担当了大量的开发工作，在这种一种开发模式下，可以说前端的开发和调试都是需要依赖于后端的web容器的支持，实际上这种开发模式根本无法做到前后端真正的分离。那到底什么是真正的前后端分离呢？
在这里插入图片描述
真正的前后端分离的方式如上图所示，

有什么好处呢？

后端开发团队，他们只要专注后端的控制层(Controller层)、服务层(service层)、数据访问层(dao层)，整个后台会通过Restful风格的API向前端去提供数据或者讲前端会通过Restful风格的API到后端获取数据。

前端开发团队，他们只要专注于前端的控制层、视图层。即除了负责前端的静态页面，还需要负责页面上所有的交互代码以及与后端API的交互工作，它要对API进行相应的调用，并获取到数据，拿到数据后对数据进行相应地处理，将数据在视图层进行相应的展示。最终在前后端分离的模式下，前端可以实现在没有后端API的情况下，还能完美地运行和完美地奔跑。

所以以这样的一种方式形成的前后端分离，无论是在开发上还是在项目部署上都可以说是各自独立且松耦合，这才是真正意义上的前后端分离。

API(Application Programming Interface,应用程序编程接口)是一些预先定义的方法，开发人员只要调用API中所提供的方法就能实现相应的功能，而且开发人员是不用知道方法内部的实现细节。

前后端分离带来的问题

作为一个web项目来说，在前后端分离模式下可以实现项目的独立开发、部署。但是最终还是需要进行前后端集成的，在集成过程中肯定要进行集成测试以及接口的联调。但是这个集成往往都是令人头痛的问题。

那么这个时候我们就想有一个自动化的工具来帮助我们自动去生成最新的API说明文档。 Swagger

SpringBoot集成swagger

1、创建项目

我这里使用的是刚刚创建的Springboot项目
在这里插入图片描述

2、导入pom依赖

在这里插入图片描述

		<!-- swagger需要的依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.3</version>
        </dependency>
3、配置静态访问资源

创建config包，粘贴我的俩个类，里面有详细注释
在这里插入图片描述

package com.lj.swaggertest.config;

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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 创建一个Docket对象
     * 调用select()方法，
     * 生成ApiSelectorBuilder对象实例，该对象负责定义外漏的API入口
     * 通过使用RequestHandlerSelectors和PathSelectors来提供Predicate，在此我们使用any()方法，将所有API都通过Swagger进行文档管理
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //标题
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                //简介
                .description("")
                //服务条款
                .termsOfServiceUrl("")
                //作者个人信息
                .contact(new Contact("lijie","","468671109@qq.com"))
                //版本
                .version("1.0")
                .build();
    }
}

package com.lj.swaggertest.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决 swagger-ui.html 404报错
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解决 doc.html 404 报错
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");

    }
}
4、运行项目

配置一下端口号，默认8080，运行
在这里插入图片描述
打开网页，输入：http://localhost:8080/doc.html
在这里插入图片描述

完成

使用方式（显示API接口的描述性释介绍在后面）

在接口的类上定义

在这里插入图片描述

/**
 * 订单信息Api接口类
 *
 * @author 李杰
 * @version 2019-12-21 李杰
 * @since 1.0
 */
@Api(value = "订单信息接口类", tags = "订单信息接口类")
@RequestMapping("/api/wecharorder/")
@RestController
在接口上定义

在这里插入图片描述

	/**
     * 提交订单
     *
     * @param paymentType 支付类型(1:微信，2:支付宝，3:积分支付)
     * @param orderId     订单编号
     * @return 支付信息
     */
    @ApiOperation(value = "创建订单", notes = "创建订单", httpMethod = "POST")
    @ApiImplicitParams({@ApiImplicitParam(name = "paymentType", value = "付款类型(1:微信，2:支付宝，3:积分支付)", required = true, paramType = "query"),
            @ApiImplicitParam(name = "orderId", value = "订单编号", required = true, paramType = "query")})
    @PostMapping("submit.do")
Swagger中查看

在这里插入图片描述

还提供接口测试试功能哟

在这里插入图片描述

API接口的常用描述注释介绍


（1）@Api：表明可供Swagger展示的接口类(多用在Controller类上面)

属性：
tags=”说明该类的作用，非空时将覆盖value的值”。
value=”描述类的作用”
basePath=”基本路径”，基本路径可不配置，在Swagger1.5 版本后不再支持。

（2）@ApiOperation：描述API方法(用在方法上面)

属性
value=”说明方法的用途、作用”
httpMethod 指定HTTP请求的方式，GET/POST等。
produces 设置MIME类型列表，如application/json，application/xml等。
notes 接口发布说明
protocols 设置特定协议，如http、https等。
response 响应类型(即返回对象)

（3）@ApiImplicitParams：用在请求的方法上，包含一组参数说,明里面包多个@ApiImplicitParam
（4）@ApiImplicitParam 是对单个参数的说明（上门代码中有例子）

属性
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
–>header --> 请求参数的获取：@RequestHeader
–> query --> 请求参数的获取：@RequestParam
–> path（用于restful接口）–> 请求参数的获取：@PathVariable
–>body（请求体）–> @RequestBody User user
–>form（不常用）
dataType：参数类型，默认String，其它值dataType=“Integer”
defaultValue：参数的默认值

（5）@ApiModelProperty 该注解写到实体类中的属性上面，用来定义属性的详细信息(注释)。

例子:
在这里插入图片描述

/** 明细编号 **/
    @ApiModelProperty(value = "明细编号", name = "historyDetailId", example = "")
    private Integer historyDetailId;
标签
swagger
前端
api
易学教程内所有资源均来自网络或用户发布的内容，如有违反法律规定的内容欢迎反馈！
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!