SpringBoot整合Swagger

引言

在前后端开发过程中，为了减少前后端程序员以及与其他团队之间的沟通成本，因此要定义一组公共的API接口文档来描述所有接口方法的信息。但是这种方式在某一方面也存在很大的弊端，如下：

• 如果开发人员所描写的接口数量众多，一方面编写API接口文档工作量巨大，另一方面因为API接口不仅包含接口的基础信息，例如：请求参数‘请求类型及接口的返回值等等，还要包含HTTP请求类型，请求头、请求参数类型等；
• 后期维护不方便，一旦编写的接口发生变化，就要修改此API接口文档；
• 接口测试不方便，一般只能靠第三方客户端来测试

一、Swagger 2简介

Swagger 2是一个开源的软件框架，可以帮助开发人员设计、构建和使用Web服务，将代码与文档结合在一起，完美的解决了上述问题，使开发人员将大部分精力集中到业务中，而不是文档的撰写。

二、SpringBoot集成Swagger

2.1引入Swagger的依赖

<dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--swagger-->
 <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <scope>compile</scope>
       <version>2.9.2</version>
</dependency>
<dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <scope>compile</scope>
       <version>2.9.2</version>
</dependency>

2.2编写Swagger 2配置类

package com.org.comunity.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
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 {

    @Bean
    Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
.apis(RequestHandlerSelectors.basePackage("com.org.comunity"))
                .build().apiInfo(new ApiInfoBuilder().description("xxxx管理系统")
                .contact(new Contact("xxx", "https://www.xxx.com", "xxxx@163.com"))
                .version("V1.0").title("API测试文档")
                .license("Apache2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .build());
    }
}

解释:
RequestHandler=Selectors.basePackage(“com.org.comunity”)
com.org.comunity为所要扫描的控制器即接口

2.3编写控制器类测试

package com.org.comunity.controller;

import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class RootController {

    @ApiOperation("测试")
    @RequestMapping("/hello")
    public String test(){
        return "Hello World!";
    }
}

Swagger 2注解解释

注解	作用	参数
@Api	表示标识这个类是swagger的资源	1.tags=“说明该类的作用，可以在UI界面上看到的注解” 2.value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
@ApiOperation	用在请求的方法上，说明方法的用途、作用，表示一个http请求的操作	value=“说明方法的用途、作用” notes="方法的备注说明"
@ApiImplicitParams	用在请求的方法上，表示一组参数说明，用于方法，包含多个 @ApiImplicitParam	name–参数ming value–参数说明 dataType–数据类型 paramType–参数类型 example–举例说明
@ApiImplicitParam	用在@ApiImplicitParams注解中，指定一个请求参数的各个方面，表示单独的请求参数	name：参数的汉字说明、解释 value：参数名 required：参数是否必须传 paramType：参数放在哪个地方 header： 请求参数的获取：
@ApiIgnore	用于类，方法，方法参数表示这个方法或者类被忽略 ,可以不被swagger显示在页面上
@RequestHeader	指定请求类型	query：请求参数的获取：
@ApiParam	用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等	name–参数名 value–参数说明 required–是否必填
@PathVariable	是获取get方式，url后面参数，进行参数绑定，对应path	body（不常用）form（不常用） dataType：参数类型，默认String，其它值dataType=“Integer” defaultValue：参数的默认值
@ApiResponses	用在请求的方法上，表示一组响应	code http的状态码 message 描述 response 默认响应类 Void reference 参考ApiOperation中配置 responseHeaders 参考 ResponseHeader 属性配置说明 responseContainer 参考ApiOperation中配置
@ApiResponse	用在@ApiResponses中，一般用于表达一个错误的响应信息	code：数字，例如400 message：信息，例如"请求参数没填好" response：抛出异常的类
@ApiModel	用于响应类上，表示一个返回响应数据的信息这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候)表示对类进行说明，用于参数用实体类接收	暂无
@ApiModelProperty	表示对model属性的说明或者数据操作更改	value–字段说明 name–重写属性名字 dataType–重写属性类型 required–是否必填 example–举例说明 hidden–隐藏
@ResponseHeader	用于方法上，设置响应头	name 响应头名称 description 头描述 response 默认响应类 Void responseContainer 参考ApiOperation中配置

黄色为常用注解

2.4启动应用访问swagger-ui

浏览器输入 http://localhost:8086/swagger-ui.html
8086为你的应用启动的端口号

用法：


以上就是SpringBoot集成Swagger 2的全部了，希望大家能够get，有问题请及时批评斧正！！！