swagger快速入门

1.什么是swagger？

Swagger是一个前后端分离下使用的API接口框架，它提供了RESTful 风格的接口生成、描述、调用和可视化。Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。swagger是一款让你更好的书写api文档的框架。

2.swagger的优势

1）支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。

2）提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

3.swagger入门案例

1）创建一个springboot项目，引入web依赖

 2）在pom文件加入下面这些依赖

　　　　　<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.2.6</version>
        </dependency>

3）写一个简单类加上两个注解

@Configuration
@EnableSwagger2  //开启swagger2
public class Swagger2 {
    
}

4）访问http://localhost:8080/swagger-ui.html就可以看到swagger页面

5）配置Swagger2类

package com.gh.swagger;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
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;

import java.util.ArrayList;


@Configuration
@EnableSwagger2  //开启swagger2
//@EnableWebMvc
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.jiang"))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        Contact concact = new Contact("fang", "http://www.baidu.com", "1179508986@qq.com");
        return new ApiInfo(
                "我是中国",
                "所示",
                "v1.0",
                "http://www.baidu.com",
                concact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()
        );
    }
}

 

6）swagger配置扫描接口

.apis(RequestHandlerSelectors.basePackage("com.gh.controller"))   //RequestHandlerSelectors配置要扫描接口的方式，basePackage指定要扫描的包

.paths          //过滤什么路径

.enable(false)  //配置不启动

.groupName()

4. swagger中的常用注解

@Api：用在类上，说明该类的作用。
@ApiOperation：注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam：用来注解来给方法入参增加说明。
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息