首页 > 其他分享 >【Swagger2】（文档版）（简洁版）(内含源代码)

【Swagger2】（文档版）（简洁版）(内含源代码)

时间：2023-02-10 10:13:51浏览次数：52  
标签：源代码 people Swagger2 swagger 文档 接口 注解 Swagger

源代码请添加笔者微信获取

微信号：FBIHackerHarryHao

微信二维码：

 

 


目录

【Swagger2】

主要内容

学习目标

一、Swagger简介

1.前言

2.Open API 是什么

3.Swagger简介

二、Springfox

三、Swagger极致用法

五、Swagger配置

1.配置基本信息

2.设置扫描的包

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

3.1自定义注解

3.2添加规则

3.3添加NotIncludeSwagger注解

4设置范围

六、Swagger2常用注解

1.Api

2.ApiOperation

3.ApiParam

4.ApiModel

5.ApiModelProperty

6.ApiIgnore

7.ApiImplicitParam

【Swagger2】

主要内容

  1. Swagger2简介
  2. Springfox
  3. Swagger2极致用法
  4. Swagger-UI使用
  5. Swagger2配置
  6. Swagger2常用注解

学习目标 

知识点

要求

Swagger2简介

掌握

Springfox简介

掌握

Swagger2极致用法

掌握

Swagger-UI使用

掌握

Swagger2配置

掌握

Swagger2常用注解

掌握

一、Swagger简介

1.前言

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

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

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

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

2.Open API 是什么

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

Open API文件允许描述整个API，包括：

每个访问地址的类型。POST或GET。
每个操作的参数。包括输入输出参数。
认证方法。
连接信息，声明，使用团队和其他信息。
Open API规范可以使用YAML或JSON格式进行编写。这样更利于我们和机器进行阅读。

OpenAPI规范（OAS）为REST API定义了一个与语言无关的标准接口，允许人和计算机发现和理解服务的功能，而无需访问源代码，文档或通过网络流量检查。正确定义后，消费者可以使用最少量的实现逻辑来理解远程服务并与之交互。

然后，文档生成工具可以使用OpenAPI定义来显示API，使用各种编程语言生成服务器和客户端的代码生成工具，测试工具以及许多其他用例。

源码和说明参照：

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#oasDocument

3.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。

附：官网地址

http://springfox.github.io/springfox/

 

附：官方源码

https://github.com/springfox/springfox

三、Swagger极致用法

编写SpringBoot项目

编写SpringBoot项目，项目中controller中包含一个Handler，测试项目，保证程序可以正确运行。

创建项目

创建项目开始=============================================================

 

 

 

 

 

 创建项目结束=============================================================

修改pom.xml

 

  导入lombok依赖

<!-- https://mvnrepository.com/artifact/org.projectlombok/lombok -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.24</version>
    <scope>provided</scope>
</dependency>

导入Spring-fox依赖

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

<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>

创建实体类People

package com.bjsxt.swagger.entity;
 
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.experimental.Accessors;
 
@Accessors(chain = true)
@AllArgsConstructor
@NoArgsConstructor
@Data
public class People {
    private Long id;
    private String name;
    private String address;
}

创建controller层

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

添加注解

在SpringBoot的启动类中添加@EnableSwagger2注解。

添加此注解后表示对当前项目中全部控制器进行扫描。应用Swagger2

package com.bjsxt.swagger;
 
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
@EnableSwagger2
@SpringBootApplication
public class SwaggerApplication {
 
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }
 
}

访问swagger-ui

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

四、Swagger-UI使用

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

 

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

 

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

 

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

 

 下面会出现Request URL以及不同状态码响应回来的结果。

 

 

 五、Swagger配置

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

1.配置基本信息

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

apiInfo:设置描述文件中info。参数类型ApiInfo

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

ApiInfoBuilder：ApiInfo构建器。

@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("北京尚学堂","http://www.bjsxt.com","[email protected]"))
                //文档标题
                .title("这里是Swagger的标题")
                //文档描述
                .description("这里是Swagger的描述")
                //文档版本
                .version("1.0.0")
                .build();
        
    }
 
 
}

显示效果如下：

 

 

 

 

 2.设置扫描的包

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

 

 

 

 就没有basic-error-controller了

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

3.1自定义注解

注解名称随意。

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

 3.2添加规则

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

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

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

先静态导入这两个包

import static com.google.common.base.Predicates.not;
import static springfox.documentation.builders.RequestHandlerSelectors.withMethodAnnotation;

 

 

 3.3添加NotIncludeSwagger注解

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

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

4设置范围

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

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

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

先静态导入下面的包

import static springfox.documentation.builders.PathSelectors.regex;

 

 

@Bean
    public Docket getDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(swaggerDemoApiInfo())
                .select()
                .paths(allowPaths())
                .apis(RequestHandlerSelectors.basePackage("com.bjsxt.swagger.controller"))
                .apis(not(withMethodAnnotation(NotIncludeSwagger.class)))
                .build();
    }
 
    private Predicate<String> allowPaths() {
        return or(regex("/demo/.*"));
    }

 

 

 

 

六、Swagger2常用注解

1.Api

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

tags：类的名称。可以有多个值，多个值表示多个副本。

description:描述，已过时。

 

 在swagger-ui.html中显示效果。

 

 

2.ApiOperation

@ApiOperation写在方法上，对方法进行总体描述

  1. value：接口描述
  2. notes：提示信息

代码示例：

 

  在swagger-ui中显示效果

 

 

3.ApiParam

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

name：参数名称

value：参数描述

required：是否是必须

 

 

 swagger-ui显示效果如下：

 

 

4.ApiModel

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

  1. value：名称
  2. description：描述

代码示例：

 

 

 

 

 5.ApiModelProperty

@ApiModelProperty可以用在方法或属性上。用于当对象作为参数时定义这个字段的内容。

value：描述

name：重写属性名

required：是否是必须的

example：示例内容

hidden：是否隐藏。

代码示例：

 

  swagger-ui.html效果展示

 

 

6.ApiIgnore

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

 

 

 

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

 swagger-ui.html效果展示

 

 

 7.ApiImplicitParam

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

name：属性名

value：描述

required：是否是必须的

paramType：属性类型

dataType：数据类型

代码示例：

 

 

@ApiOperation(value = "接口描述",notes = "接口提示信息")
    @ApiImplicitParam(name="address",value = "地址",required = true,paramType = "query",dataType = "string")
    @PostMapping("/getPeople4")
    public People getPeople4(Long id, @ApiParam(value = "姓名",required = true) String name, String address) {
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress(address);
        return people;
    }

 

swagger-ui.html效果展示

 

 

 

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

 

 

   @ApiOperation(value = "接口描述",notes = "接口提示信息")
    @PostMapping("/getPeople5")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name="id",value="编号",required = true),
            @ApiImplicitParam(name="name",value="姓名",required = true)
    })
    public People getPeople5(Long id, @ApiParam(value = "姓名",required = true) String name, String address) {
        People people = new People();
        people.setId(id);
        people.setName(name);
        people.setAddress(address);
        return people;
    }

 

swagger-ui.html效果展示

 

 

 

标签：源代码,people,Swagger2,swagger,文档,接口,注解,Swagger
From： https://www.cnblogs.com/huanghaoheng/p/17107948.html

相关文章

赞助商

阅读排行

网站主页关于我们联系我们网站地图

本网站内容转载自其他媒体，侵权联系[admin##ips99.com]。

Copyright © 2020-2023 IPS99 版权所有 IPS99