Swagger总结

目录

简介:

openAPI

Springfox:

        简介

        Springfox的使用

        SwaggerUI的使用

        Swagger配置

        设置扫描的包

        设置范围

Swagger常用注解:

        控制类、方法生成接口信息

        @ApiParam

        @ApiModel

        @ApiModelProperty

        @ApiIgnore

        @ApiImplicitParam


 

 

部分图片来自百战程序员 

简介:

接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要,但是由于项目周期等原因后端人员经常出现无法及时更新,导致前端人员抱怨接口文档和实际情况不一致。很多人员会抱怨别人写的接口文档不规范,不及时更新。如果接口文档可以实时动态生成就不会出现上面问题,Swagger可以完美地解决上面的问题。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful 风格的 Web 服务,可用于接口的文档在线自动生成以及功能测试。

openAPI

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

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

 

Open API 规范可以使用YAML或 JSON格式进行编写,这样更利于我们和机器进行阅读。

Swagger和Open API

Swagger 是一套围绕 Open API 规范构建的开源工具,可以帮助设计,构建,记录和使用 REST API。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 中。在 SwaggerHub 中可以完成上面项目的所有工作,需要注册账号,分免费版和收费版。使用 Swagger,就是把相关的信息存储在它定义的描述文件里面(yml 或 json 格式),再通过维护这个描述文件可以去更新接口文档,以及生成各端代码

Springfox:

        简介

使用 Swagger 时如果碰见版本更新,只需要更改Swagger的描述文件即可。但是在频繁地更新项目版本时很多开发人员认为即使修改描述文件(yml 或 json)也有一定的工作负担,久而久之就直接修改代码,而不去修改描述文件了,这样基于描述文件生成接口文档也就失去了意义。

 

 由于Spring的流行,Marty Pitt 编写了一个基于Spring 的组件swagger-springmvc。Spring-fox 就是根据这个组件发展而来的全新项目。Spring-fox 是根据代码生成接口文档,所以正常的进行更新项目版本,修改代码即可,而不需要跟随修改描述文件。Spring-fox 利用自身 AOP 特性,把 Swagger 集成进来,底层还是Swagger。但是使用起来确方便很多。所以在实际开发中,都是直接使用 spring-fox。官网地址:

GitHub - springfox/springfox: Automated JSON API documentation for API's built with Spring

        Springfox的使用

1、创建SpringBoot项目,添加spring-fox依赖

在项目的pom.xml中导入Spring-fox依赖。选择版本2.9.2,所以导入的依赖也是这个版本。其中 springfox-swagger2 是核心内容的封装。springfox-swagger-ui 是对 swagger-ui 的封装。


  io.springfox
  springfox-swagger2
  2.9.2


  io.springfox
  springfox-swagger-ui
  2.9.2

2、创建实体类

public class People {
    private int id;
    private String name;
    private String address;

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getAddress() {
        return address;
    }

    public void setAddress(String address) {
        this.address = address;
    }
}

3、创建controller

@RestController
@RequestMapping("/people")
public class MyController {

    @RequestMapping("/getPeople")
    public People getPeople(int id,String name){
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress("深圳");
        return people;
    }
}

4、在启动类中添加@EnableSwagger2注解,添加此注解后表示对当前项目中全部控制器进行扫描,应用Swagger2。

@SpringBootApplication
@EnableSwagger2
public class SwaggerBlogApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerBlogApplication.class, args);
    }

}

访问 swagger-ui

启动项目后在浏览器中输入 http://IP:port/swagger-ui.html即可以访问到 swagger-ui 页面,在页面中可以可视化的进行操作项目中所有接口。

Swagger总结_第1张图片

        SwaggerUI的使用

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

Swagger总结_第2张图片

每个控制器包含该控制器下所有的方法及访问方式。如果使用的是@RequestMapping 进行映射,将显示下面的所有请求方式。如果使用@PostMapping 将只有 Post 方式可以能访问,下面也就只显示Post 的一个。

Swagger总结_第3张图片

点击某个请求方式中 try it out

Swagger总结_第4张图片

输入参数值,完成后点击 Execute 按钮

Swagger总结_第5张图片

下面会出现 Request URL 以及响应结果。

Swagger总结_第6张图片

 

        Swagger配置

可以在项目中创建 SwaggerConfig,进行配置文档内容

@Configuration
public class SwaggerConfig{
  @Bean
  public Docket getDocket(){
    return new Docket(DocumentationType.SWAGGER_2)
       .apiInfo(swaggerDemoApiInfo())
       .select()
       .build();
   }

    private ApiInfoswaggerDemoApiInfo(){
        return new ApiInfoBuilder()
       .contact(new Contact("北京尚学堂",           "http://www.bjsxt.com","[email protected]"))
    //文档标题
     .title("这里是Swagger的标题")
    //文档描述
     .description("这里是Swagger的描述")
    //文档版本
     .version("1.0.0")
     .build();
    }
}
  • 配置基本信息

配置项

含义

Docket

摘要对象,通过对象配置描述文件的信息。

apiInfo

设置描述文件中 info,参数类型 ApiInfo

select()

返回 ApiSelectorBuilder 对象,通过对象调用 build()可以创建 Docket 对象

ApiInfoBuilder

ApiInfo 构建器

显示效果如下:

Swagger总结_第7张图片

 

        设置扫描的包

  • 设置扫描的包

可以通过 apis()方法设置哪个包中内容被扫描

@Bean
public Docket getDocket() {
 return new Docket(DocumentationType. SWAGGER_2)
    .apiInfo(swaggerDemoApiInfo())
    .select()
    .apis(RequestHandlerSelectors.basePackage("com.itbaizhan.swagger_blog.controller"))
    .build();
}

 

        设置范围

通过下面的代码

public ApiSelectorBuilder paths(Predicate selector)

可以设置满足什么样规则的 url 被生成接口文档。可以使用正则表达式进行匹配。

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

@Bean
public Docket getDocket(){
    return new Docket(DocumentationType. SWAGGER_2)
     .apiInfo(swaggerDemoApiInfo())
     .select()
     .paths(allowPaths())
     .build();
}
private Predicate allowPaths(){
  return or(regex("/demo/.*"));
} 

 如何希望全部扫描可以使用
paths(PathSelectors.any())

 

Swagger常用注解:

        控制类、方法生成接口信息

  • @Api

注解名称

参数

含义

@Api

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

tags

类的名称,可以有多个值,多个值表示多个副本

description

描述

代码示例如下:

@RestController
@RequestMapping("/people")
@Api(tags = "TestApi",description = "描述")
public class MyController {

    @PostMapping("/getPeople")
    public People getPeople(int id,String name){
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress("深圳");
        return people;
    }
}

在 swagger-ui.html 中显示效果

 Swagger总结_第8张图片

 

 

  • @ApiOperation

注解名称

参数

含义

@ApiOperation

写在方法上,对方法进行总体描述

value

接口描述

notes

提示信息

代码示例:

@RestController
@RequestMapping("/people")
@Api(tags = "TestApi",description = "描述")
public class MyController {

    @ApiOperation(value = "获取人类",notes = "获取人类的信息")
    @PostMapping("/getPeople")
    public People getPeople(int id,String name){
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress("深圳");
        return people;
    }
}

在 swagger-ui 中显示效果

Swagger总结_第9张图片

 

        @ApiParam

  • ApiParam

注解名称

参数

含义

@ApiParam

写在控制器方法参数前面。用于对参数进行描述或说明是否为必添项等说明

name

参数名称

value

参数描述

required

是否是必须

在代码中示例:

@RestController
@RequestMapping("/people")
@Api(tags = "TestApi",description = "描述")
public class MyController {

    @ApiOperation(value = "获取人类",notes = "获取人类的信息")
    @PostMapping("/getPeople")
    public People getPeople(int id,@ApiParam(value = "姓名",required = true) String name){
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress("深圳");
        return people;
    }
}

swagger-ui 显示效果如下: 

Swagger总结_第10张图片

        @ApiModel

  • ApiModel

注解名称

参数

含义

@ApiModel

是类上注解,主要应用 Model,也就是说这个注解一般都是写在实体类上

value

名称

description

描述

代码示例:

@ApiModel(value = "人类",description = "描述")
public class People {......}

swagger-ui.html 效果展示 

Swagger总结_第11张图片

        @ApiModelProperty

注解名称

参数

含义

@ApiModelProperty

一般用于实体类方法、属性的说明

value

字段说明

name

重写属性名

required

是否必须

example

示例内容

hidden

是否隐藏

 

代码示例:

@ApiModel(value = "人类",description = "描述")
public class People {
    private int id;
    @ApiModelProperty(value = "姓名",required = true,example = "张三")
    private String name;
    private String address;
    ......

}

 Swagger总结_第12张图片

 

        @ApiIgnore

注解名称

含义

@ApiIgnore

用于方法或类或参数上,表示这个方法或类被忽略

@RestController
@RequestMapping("/people")
@Api(tags = "TestApi",description = "描述")
@ApiIgnore
public class MyController {

    @ApiOperation(value = "获取人类",notes = "获取人类的信息")
    @PostMapping("/getPeople")
    public People getPeople(int id,@ApiParam(value = "姓名",required = true) String name){
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress("深圳");
        return people;
    }
}

 Swagger总结_第13张图片

 

        @ApiImplicitParam

注解名称

参数

含义

@ApiImplicitParam

用在控制器方法上,表示单独的请求参数,总体功能和@ApiParam 类似。

value

对接口中的参数进行简单必要的描述

name

描述接口中参数的名称

required

是否必须

paramType

接口中的参数应该用在哪个地方,常用的位置有:header、query 、path

dataType

接口中参数的类型

代码示例:

@RestController
@RequestMapping("/people")
@Api(tags = "TestApi",description = "描述")
//@ApiIgnore
public class MyController {

    @ApiOperation(value = "获取人类",notes = "获取人类的信息")
    @PostMapping("/getPeople")
    @ApiImplicitParam(value = "编号",name = "id")
    public People getPeople(int id, @ApiParam(value = "姓名",required = true) String name){
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress("深圳");
        return people;
    }
}

swagger-ui.html 效果展示 

Swagger总结_第14张图片

如果希望在方法上配置多个参数时,使用@ApiImplicitParams 进行配置。示例如下:

@ApiImplicitParams(value={@ApiImplicitParam(name="id",value="编号",required=true),@ApiImplicitParam(name="name",value="姓名",required=true)})

你可能感兴趣的:(java,restful,开发语言,后端)