一文教你使用Swagger---适合新手小白(结合实战)

1.什么是Swagger 

   Swagger----在线自动生成接口文档,是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务,可用于接口的文档在线自动生成以及功能测试。

2.Swagger与OpenAPI  

   OpenAPI规范OpenAPI Specification以前叫做Swagger规范,是REST API的API描述格式。Open API 文件允许描述整个API,包括:

  • 每个访问地址的类型,POST或GET
  • 每个操作的参数,包括输入输出参数
  • 认证方法
  • 连接信息、声明,使用团队和其他信息

   OpenAPI规范可以使用YAML或jSON格式进行编写,这样更利于阅读。Swagger是一套围绕Open API规范构建的开源工具,可以帮助设计、构建,记录和使用REST API。

3.Swagger工具包括的组件

Swagger Editor:基于浏览器编辑器,可以在里面编写Open API规范。类似Markdown具有实时预览描述文件的功能。

Swagger UI:将Open API规范呈现为交互式API文档。用可视化UI展示描述文件。

Swagger Codegen:将OpenAPI规范生成为服务器存根和客户端库,通过Swagger Codegen可以将描述文件生成html格式和cwiki形式的接口文档,同时也可以生成多种语言的客户端和服务端代码。

Swagger Inspector:和Swagger UI欧典类似,但是可以返回更多信息,也会保存请求的实际参数数据。

Swagger Hub 继承了上面所有项目的各个功能,你可以以项目和版本为单位,将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作。需要注册帐号,分免费版和收费版。使用Swagger,就是把相关的信息存储在他定义的描述文件里面(yml或json格式),再通过维护这个描述文件可以去更新接口文档,以及生成各端代码。

4.Springfox的使用

1.引入依赖


    io.springfox
    springfox-swagger2
    2.9.2


     io.springfox
     springfox-swagger-ui
     2.9.2

2.启动类上加注解

一文教你使用Swagger---适合新手小白(结合实战)_第1张图片

3.启动后浏览器输入对应端口号+/swagger-ui.html.

我的是 http://localhost:8080/swagger-ui.html#

4.效果如下

一文教你使用Swagger---适合新手小白(结合实战)_第2张图片

5.SwaggerUI的使用和配置

    访问swagger-ui.html可以在页面中看到所有需要生成接口文档的控制器名称。

    每个控制包含该控制器下所有的方法及访问方式。如果使用的是@RequestMapping进行映射,将在显示所有的请求方式,如上图所示。假设使用@PostMapping,那么就只会显示Post的那个。

一文教你使用Swagger---适合新手小白(结合实战)_第3张图片 点击某个请求方法中的try it out

一文教你使用Swagger---适合新手小白(结合实战)_第4张图片

 输入对应的参数,然后点击execute执行,将会出现Request URL以及相应结果。

一文教你使用Swagger---适合新手小白(结合实战)_第5张图片

5.Swagger配置类的实现

一文教你使用Swagger---适合新手小白(结合实战)_第6张图片

效果:一文教你使用Swagger---适合新手小白(结合实战)_第7张图片

6.自定义注解排除扫描

1.创建NoIncludeSwagger接口

package cn.itcast;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface NoIncludeSwagger {
}

2.配置到Swagger配置类中

一文教你使用Swagger---适合新手小白(结合实战)_第8张图片

3.在需要排除了类上加上注解即可

一文教你使用Swagger---适合新手小白(结合实战)_第9张图片

效果如下:

一文教你使用Swagger---适合新手小白(结合实战)_第10张图片

7.设置范围

所谓设置范围实际就是可以设置满足什么样规则的url能被生成在接口文档中,可以使用正则表达式进行匹配。

下面例子中表示只有以/demo/开头的url才能被swagger生成接口文档。

一文教你使用Swagger---适合新手小白(结合实战)_第11张图片

如果希望所有接口都使用Swagger:

paths(PathSelectors.any())

8.常用注解

  1. Api
注解名称 参数 含义
@Api 类上注解,控制整个类生成接口信息的内容
tags 类的名称,可以有多个值,多个值表示多个副本
description 概述

类上注解 控制整个类生成接口信息的内容

package cn.itcast.controller;

import cn.itcast.NoIncludeSwagger;
import cn.itcast.domain.People;
import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/people")
@Api(tags = {"myDemo"},description = "描述")
public class DemoController {
//    @NoIncludeSwagger
    @PostMapping("/getPeople")
    public People getPeople(Long id, String name){
        People peo = new People();
        peo.setId(id);
        peo.setName(name);
        peo.setAddress("北京");
        return peo;
    }
}

一文教你使用Swagger---适合新手小白(结合实战)_第12张图片

2. ApiOperation
注解名称 参数 含义
@ApiOperation 写在方法上,对方法进行总体描述
value 接口描述
notes 提示信息
@RestController
@RequestMapping("/people")
@Api(tags = {"myDemo"},description = "描述")
public class DemoController {
//    @NoIncludeSwagger
    @ApiOperation(value = "获取人员信息",notes = "通过人员编号和名称获取人员信息")
    @PostMapping("/getPeople")
    public People getPeople(Long id, String name){
        People peo = new People();
        peo.setId(id);
        peo.setName(name);
        peo.setAddress("北京");
        return peo;
    }
}

一文教你使用Swagger---适合新手小白(结合实战)_第13张图片

3. ApiParam
注解名称 参数 含义
@ApiParam 写在方法参数前面。用于对参数进行描述或说明是否为必填项等
name 参数名称
value 参数描述
required 是否是必须

一文教你使用Swagger---适合新手小白(结合实战)_第14张图片

一文教你使用Swagger---适合新手小白(结合实战)_第15张图片 4. ApiModel
注解名称 参数 含义
@ApiParam 是类上注解,主要应用Model,也就是说这个注解一般都是写在实体类上
value 名称
description 描述

一文教你使用Swagger---适合新手小白(结合实战)_第16张图片

一文教你使用Swagger---适合新手小白(结合实战)_第17张图片 5. ApiModelProperty
注解名称 参数 含义
@ApiModelProperty 一般用于方法,属性的说明
value 字段说明
name 重写属性名
required 是否必须
example 示例内容
hiden 是否隐藏

一文教你使用Swagger---适合新手小白(结合实战)_第18张图片

一文教你使用Swagger---适合新手小白(结合实战)_第19张图片 6. ApiIgnore
注解名称 含义
@ApiIgnore 用于方法或类或参数上,表示这个方法或类被忽略,和之前讲解的自定义注解@NotIncludeSwagger效果类似。只是这个注解是Swagger内置的注解,而@NotIncludeSwagger是我们自定义的注解
7. ApiImplicitParam
注解名称 参数 含义
@ApiImpliciParam 用在方法上,表示单独的请求参数,总体功能和@ApiParam类似。
value 对接口中的参数进行简单必要的描述
name 描述接口中参数的名称
required 是否必须
paramType 接口中的参数应该用在那个地方,常用的位置有:header,query,path
dataType 接口中参数的类型

由于后两个效果类似与前面就不再做演示

你可能感兴趣的:(swagger,经验分享)