当前位置:首页 > 服务端 > Swagger学习笔记

Swagger学习笔记

2022年08月06日 13:36:45服务端4

前言

  接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要,但是由于项 目周期等原因后端人员经常出现无法及时更新,导致前端人员抱怨接 口文档和实际情况不一致。

  很多人员会抱怨别人写的接口文档不规范,不及时更新。当时当 自己写的时候确实最烦去写接口文档。这种痛苦只有亲身经历才会牢 记于心。

  如果接口文档可以实时动态生成就不会出现上面问题。

  Swagger 可以完美的解决上面的问题。

Open API

  Open API 规范(OpenAPI Specification)以前叫做 Swagger 规范,是REST API 的 API 描述格式。

  Open API 文件允许描述整个 API,包括:

    · 每个访问地址的类型。POST 或 GET。

    ·每个操作的参数。包括输入输出参数。

    ·认证方法。

    ·连接信息,声明,使用团队和其他信息。

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

  OpenAPI 规范(OAS)为 RESTful API 定义了一个与语言无关的标 准接口,允许人和计算机发现和理解服务的功能,而无需访问源代码, 文档或通过网络流量检查。正确定义后,消费者可以使用最少量的实 现逻辑来理解远程服务并与之交互。然后,文档生成工具可以使用 OpenAPI 定义来显示 API,使用各 种编程语言生成服务器和客户端的代码生成工具,测试工具以及许多 其他用例。

Swagger 简介

  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 中。在 Swagger Hub 中可以完成上面项目的所有工作,需要注册账号,分免费版和收费版。

    使用 Swagger,就是把相关的信息存储在它定义的描述文件里面(yml 或 json 格式),再通过维护这个描述文件可以去更新接口文档, 以及生成各端代码。

一、Springfox

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

  Marty Pitt 编写了一个基于 Spring 的组件 swagger-springmvc。 Spring-fox 就是根据这个组件发展而来的全新项目。

  Spring-fox 是根据代码生成接口文档,所以正常的进行更新项目版本,修改代码即可,而不需要跟随修改描述文件。

  Spring-fox 利用自身 AOP 特性,把 Swagger 集成进来,底层还是Swagger。但是使用起来确方便很多。 所以在实际开发中,都是直接使用 spring-fox。

springfox快速使用

1、编写一个SpringBoot项目,勾选web下的spring web,创建people类,和一个controller

Swagger学习笔记 _ JavaClub全栈架构师技术笔记
package com.soldier.pojo;

/**
 * @Author soldier
 * @Date 2020/3/11 11:18
 * @Version 1.0
 * @Description:
 */
public class People {
    private Long id;
    private String name;
    private String address;

    public Long getId() {
        return id;
    }

    public void setId(Long 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;
    }
}
People.class
package com.soldier.controller;

import com.soldier.pojo.People;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @Author soldier
 * @Date 2020/3/11 11:19
 * @Version 1.0
 * @Description:
 */
@RestController
@RequestMapping("/people")
public class DemoController {

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

2、导入spring-box依赖

<!--spring-fox依赖-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

3、启动类添加@EnableSwagger2注解

Swagger学习笔记 _ JavaClub全栈架构师技术笔记

4、启动项目,访问Swagger UI

http://localhost:8080/swagger-ui.html

 

二、Swagger UI的使用

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

Swagger学习笔记 _ JavaClub全栈架构师技术笔记

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

 Swagger学习笔记 _ JavaClub全栈架构师技术笔记

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

Swagger学习笔记 _ JavaClub全栈架构师技术笔记

   · 会出现界面要求输入的值。输入完成后点击 Execute 按钮

Swagger学习笔记 _ JavaClub全栈架构师技术笔记

   · 下面会出现 Request URL 已经不同状态码相应回来的结果:

Swagger学习笔记 _ JavaClub全栈架构师技术笔记

 

三、Swagger的配置

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

1、配置基本信息

  Docket:摘要对象,通过对象配置描述文件的信息。 apiInfo:设置描述文件中 info。参数类型 ApiInfo

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

  ApiInfoBuilder:ApiInfo 构建器。

项目中新建一个配置类:

package com.soldier.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @Author soldier
 * @Date 2020/3/11 11:42
 * @Version 1.0
 * @Description: Swagger配置
 */
@Configuration
public class SwaggerConfig {

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

    private ApiInfo swaggerDemoApiInfo() {
        return new ApiInfoBuilder()
                .contact(new Contact("百度", "www.baidu.com", "baidu@163.com"))
                // 标题
                .title("这是Swagger的标题")
                // 描述
                .description("这是Swagger的描述")
                // 版本
                .version("1.0.0")
                .build();
    }
}

  重启项目,访问【http://localhost:8080/swagger-ui.html】,效果如下:

Swagger学习笔记 _ JavaClub全栈架构师技术笔记

2、设置扫描的包

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

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

3、自定义注解设置不需要生成接口文档的方法

  1)自定义注解,名称可以随便取

package com.soldier.interfaceDemo;

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

/**
 * @Author soldier
 * @Date 2020/3/11 12:11
 * @Version 1.0
 * @Description: 自定义注解
 */
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface NotIncludeSwagger {
}

  2)添加规则

    通 过 public ApiSelectorBuilder apis(Predicate<RequestHandler> selector)可以设置生成规则。

    public static <T> Predicate<T> not(Predicate<T> predicate) :表示不 允许的条件。

    withMethodAnnotation:表示此注解是方法级别注解。

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
           .apiInfo(swaggerDemoApiInfo())
           .select()
//         .apis(RequestHandlerSelectors.basePackage("com.soldier.controller"))
           // 自定义注解设置不需要生成接口文档的方法
           .apis(not(withMethodAnnotation(NotIncludeSwagger.class)))
           .build();
}

  3)添加 @NotIncludeSwagger 注解

    在不需要生成接口文档的方法上面添加@NotIncludeSwagger 注 解后,该方法将不会被 Swagger 进行生成在接口文档中。

@NotIncludeSwagger
@RequestMapping("/getPeople2")
public People getPeople2(Long id, String name, String address) {
    People people = new People();
    people.setId(id);
    people.setName(name);
    people.setAddress(address);
    return people;
}

    添加 @NotIncludeSwagger 前的:

      Swagger学习笔记 _ JavaClub全栈架构师技术笔记

    添加 @NotIncludeSwagger 后的效果:

       Swagger学习笔记 _ JavaClub全栈架构师技术笔记

4、设置范围

  通过 public ApiSelectorBuilder paths(Predicate<String> selector) 可以设置满足什么样规则的 url 被生成接口文档。可以使用正则表达式 进行匹配。

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

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

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
           .apiInfo(swaggerDemoApiInfo())
           .select()
//         .apis(RequestHandlerSelectors.basePackage("com.soldier.controller"))
           // 自定义注解设置不需要生成接口文档的方法
//         .apis(not(withMethodAnnotation(NotIncludeSwagger.class)))
           // 设置范围:以/demo/开头的 url 才能被 swagger 生成接口文档
           // 如何希望全部扫描可以使用 paths(PathSelectors.any())
           .paths(allowPaths())
           .build();
}

private Predicate<String> allowPaths() {
    return or(regex("/demo/.*"));
}

 

四、Swagger2 常用注解

  1)Api

  @Api 是类上注解。控制整个类生成接口信息的内容。 tags:类的名称 可以有多个值 多个值表示多个副本,description:描述 已过时。

@RestController
@RequestMapping("/people")
@Api(tags = {"myDemo"}, description = "DemoController描述")
public class DemoController {

  在swagger-ui.html 显示的效果:

Swagger学习笔记 _ JavaClub全栈架构师技术笔记

   2)ApiOperation

  @ApiOperation 写在方法上,对方法进行总体描述--》value:接口描述,notes:提示信息

@RequestMapping("/getPeople")
@ApiOperation(value = "接口描述", notes = "提示信息")

  页面效果:

Swagger学习笔记 _ JavaClub全栈架构师技术笔记

  3)ApiParam

  @ApiParam 写在方法参数前面。用于对参数进行描述或说明是否 为必添项等说明--》name:参数名称,value:参数描述,required:是否是必须

@RequestMapping("/getPeople")
@ApiOperation(value = "接口描述", notes = "提示信息")
public People getPeople(Long id, @ApiParam(value = "姓名 这个是参数描述", required = true) String name) {

  页面效果:

Swagger学习笔记 _ JavaClub全栈架构师技术笔记

   4)ApiModel

  @ApiModel 是类上注解,主要应用 Model,也就是说这个注解一 般都是写在实体类上--》value:名称,description:描述

@ApiModel(value = "名称:人类", description = "描述")
public class People {

  在swagger-ui.html 显示的效果:

Swagger学习笔记 _ JavaClub全栈架构师技术笔记

  5)ApiModelProperty

  @ApiModelProperty 可以用在方法或属性上。用于当对象作为参数时定义这个字段的内容--》value:描述,name:重写属性名,required:是否是必须的,example:示例内容,hidden:是否隐藏。

@ApiModelProperty(value = "描述:姓名", name = "重写属性名:name", required = true, example = "张三")
private String name;

  页面效果:

Swagger学习笔记 _ JavaClub全栈架构师技术笔记

  6)ApiIgnore

  @ApiIgnore 用于方法或类或参数上,表示这个方法或类被忽略。 和之前讲解的自定义注解@NotIncludeSwagger 效果类似。只是这个注 解是 Swagger 内置的注解,而@NotIncludeSwagger 是我们自定义的注解。

  7)ApiImplicitParam

  @ApiImplicitParam 用在方法上,表示单独的请求参数,总体功能 和@ApiParam 类似--》name:属性名,value:描述,required:是否是必须的,paramType:属性类型,dataType:数据类型

@RequestMapping("/getPeople2")
@ApiImplicitParam(name = "address",value = "地址",required = true,paramType = "query",dataType = "string")
public People getPeople2(Long id, String name, String address) {

  页面效果:

Swagger学习笔记 _ JavaClub全栈架构师技术笔记

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

@RequestMapping("/getPeople2")
@ApiImplicitParams(value={
       @ApiImplicitParam(name="id",value = "编号",required = true),
       @ApiImplicitParam(name="name",value = "姓名",required = true)
})
public People getPeople2(Long id, String name, String address) {

  页面效果:

Swagger学习笔记 _ JavaClub全栈架构师技术笔记

 

五、源码地址

点击前往  https://github.com/soldiergit/swagger-demo.git

作者:soldier_cnblogs
来源链接:https://www.cnblogs.com/soldier-cnblogs/p/12461580.html

版权声明:
1、JavaClub(https://www.javaclub.cn)以学习交流为目的,由作者投稿、网友推荐和小编整理收藏优秀的IT技术及相关内容,包括但不限于文字、图片、音频、视频、软件、程序等,其均来自互联网,本站不享有版权,版权归原作者所有。

2、本站提供的内容仅用于个人学习、研究或欣赏,以及其他非商业性或非盈利性用途,但同时应遵守著作权法及其他相关法律的规定,不得侵犯相关权利人及本网站的合法权利。
3、本网站内容原作者如不愿意在本网站刊登内容,请及时通知本站(javaclubcn@163.com),我们将第一时间核实后及时予以删除。


本文链接:https://www.javaclub.cn/server/18412.html

标签: Swagger
分享给朋友:

“Swagger学习笔记” 的相关文章

SpringBoot整合Swagger3生成接口文档

SpringBoot整合Swagger3生成接口文档

  前后端分离的项目,接口文档的存在十分重要。与手动编写接口文档不同,swagger是一个自动生成接口文档的工具,在需求不断变更的开发环境下,手动编写文档的效率实在太低。与新版的swagger3相比swagger2配置更少,使用更加方便。 一、pom文件中引入Swagger3依赖...

替换swagger-ui,选择款神器—knife4j

替换swagger-ui,选择款神器—knife4j

    一、介绍 knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案(在非Java项目中也提供了前端UI的增强解决方案),前身是swagger-bootstrap-ui,取名knife4j是希望她能像一把匕首一样小...

Swagger实现API文档功能

Swagger实现API文档功能

介绍: wagger也称为Open API,Swagger从API文档中手动完成工作,并提供一系列用于生成,可视化和维护API文档的解决方案。简单的说就是一款让你更好的书写API文档的框架。 我们为什么选择swagger,现在的网站开发结果越来越注重前后端的分离,比如以前的...

.net core在Ocelot网关中统一配置Swagger

.net core在Ocelot网关中统一配置Swagger

最近在做微服务的时候,由于我们是采用前后端分离来开发的,提供给前端的直接是Swagger,如果Swagger分布在各个API中,前端查看Swagger的时候非常不便,因此,我们试着将Swagger集中放到网关中。 这里我用两个API项目(一个BasicDataApi,一个User...

swagger整合springboot的使用

swagger整合springboot的使用

什么是swagger? Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口,可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服...

配置 Swagger 带 token 访问的两种方式

配置 Swagger 带 token 访问的两种方式

推荐使用全局的方式 1. 每个接口单独传 import com.google.common.collect.Lists; import org.springframework.beans.factory.annotation.Value; impo...

ABP使用NSwagStudio for Swagger Api生成ServiceProxies

ABP使用NSwagStudio for Swagger Api生成ServiceProxies

案例主要是使用NSwag来生成ABP for angular 2+的客户端代码。 NSwagStudio 下载地址 比较强大、可以生成TypeScript、WebApi Controller、CSharp Client  1:运行Web.Host项目&n...

swagger-ui 美化版

swagger-ui 美化版

简介 Swagger UI允许任何人(无论您是开发团队还是用户)都可以可视化API资源并与之交互,而无需任何实现逻辑。它是根据您的OpenAPI(以前称为Swagger)规范自动生成的,具有可视化文档,可简化后端实现和客户端使用,号称世界上最流行的API框架。 特点...

Swagger结合mustache模板生成后台接口代码、以及前后台建模代码

Swagger结合mustache模板生成后台接口代码、以及前后台建模代码

之前项目中使用的的thrift来建模,维护前后台模型以及rest接口,前台使用的是angular2;  但是使用thrift只能生成建模,后台的rest接口的Controller文件还是需要手动去写,一旦接口改动就会涉及到很多方面。 由此准备使用Swagger和m...

.NET Core和Swagger 生成 Api 文档

.NET Core和Swagger 生成 Api 文档

测试/生产环境的BUG 这里更新一下在本地调试正常,在INT/PROD上抛错,错误信息为: /**/.xml(Swagger json file) 文件找不到,在startup 里builder 的时候抛出错误。 解决方案: 编辑.csproj文件,修改输出路径...

发表评论

访客

◎欢迎参与讨论,请在这里发表您的看法和观点。