swagger2

最新推荐文章于 2024-05-02 17:24:44 发布

肥电

最新推荐文章于 2024-05-02 17:24:44 发布

阅读量184

点赞数 1

分类专栏： Java swagger 文章标签： restful java swagger2

本文链接：https://blog.csdn.net/qq_41141022/article/details/120820933

版权

Java 同时被 2 个专栏收录

9 篇文章 0 订阅

订阅专栏

swagger

1 篇文章 0 订阅

订阅专栏

1.Swagger简介

1.1.前言

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

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

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

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

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

1.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格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码

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

3.Swagger使用

3.1.编写SpringBoot项目

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

@Controller
public class FirstController {
    @RequestMapping("getUserName")
    @ResponseBody
    public String getUserName(String id) {
        return "stonebridge：" + id;
    }

    @RequestMapping(value = "testGetMethod", method = RequestMethod.GET)
    @ResponseBody
    public String testGetMethod() {
        return "getMethod";
    }

    @RequestMapping(value = "testPostMethod", method = RequestMethod.POST)
    @ResponseBody
    public String testPostMethod() {
        return "postMethod";
    }
}

3.2.导入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>

3.3.添加注解

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

@EnableSwagger2是springfox提供的一个注解，代表开启Swagger2相关技术支持。添加此注解后表示对当前项目中全部控制器进行扫描，做Swagger2文档定值。

@SpringBootApplication
@EnableSwagger2
public class SwaggerDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerDemoApplication.class, args);
    }
}

3.4.访问swagger-ui

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

4.Swagger-UI使用

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

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

在swagger-ui中显示效果

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

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

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

5.Swagger配置

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

5.1.配置基本信息

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

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

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

ApiInfoBuilder：ApiInfo构建器。

@Configuration
public class SwaggerConfig {
    /**
     * 创建Docket类型的对象，并使用spring容器管理
     * Docke是swagger中的全局配置对象
     *
     * @return
     */
    @Bean
    public Docket getDocket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(swaggerDemoApiInfo()) 
                .select().build();
    }

    private ApiInfo swaggerDemoApiInfo() {
        //api帮助文档的描述信息。information。
        return new ApiInfoBuilder()
                .contact(new Contact(     //配置swagger文档主题内容
                        "stonebridge的swagger练习项目的开发接口文档", //是文档的发布者这名称
                        "http://www.bjsxt.com",  //文档发布者的网站地址，一般为企业网站
                        "xxx@163.com"))   //文档发布者的电子邮箱
                //文档标题
                .title("这里是开发接口文档的标题")
                //文档描述
                .description("这里是开发接口文档的描述")
                //文档版本
                .version("1.0.1")
                .build();
    }
}

显示效果如下

5.2.设置扫描的包

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

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(swaggerDemoApiInfo())
        //获取Docket中的选择器。返回是ApiSelectorBuilder，专门用于选择器构建。如：扫描哪些包里面的注解
        .select()
        //是ApiSelectorBuilder的方法，设置具体扫描包及其子包
        .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))
        .build();
}

5.3.设置路径范围

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

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

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

@Bean
public Docket getDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(swaggerDemoApiInfo())
        //获取Docket中的选择器。返回是ApiSelectorBuilder，专门用于选择器构建。如：扫描哪些包里面的注解
        .select()
        .paths(
        Predicates.or( // 多个规则符合任意一个即可通过。
            PathSelectors.regex("/test1/.*"), // 使用正则表达式，约束生成API文档的路径地址。
            PathSelectors.regex("/swagger2/.*")
        )
    )
        //是ApiSelectorBuilder的方法，设置具体扫描包及其子包
        .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))
        .build();
}

6.Swagger2常用注解

6.1.Api

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

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

description:描述，已过时。

@Controller
/**
 * @Api - 描述当前类型生成帮助文档的信息
 *  属性 -
 *    - tags ： 给当前类型定义别名，可以有多个。定义几个别名，在ui视图中就显示几个控制器访问菜单。
 *    - description ： 给当前类型生成的帮助文档定义一个描述信息。
 */
@Api(tags = {"首页业务处理器"}, description = "主要用于处理首页业务")
public class FirstController {
//todo
}

在swagger-ui中显示效果

6.2.ApiOperation

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

value：接口描述
lnotes：提示信息

代码示例：

@RequestMapping(value = "testPostMethod", method = RequestMethod.POST)
@ResponseBody
@ApiOperation(value="post方法，执行数据新增操作", notes = "Swagger学习使用-处理POST请求的方法")
public String testPostMethod() {
    return "postMethod";
}

在swagger-ui中显示效果

6.3.ApiParam

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

name：参数名称

value：参数描述

required：是否是必须

代码示例：

@RequestMapping(value = "getUserName", method = RequestMethod.POST)
@ResponseBody
public String getUserName(
    @ApiParam(name = "用户id", value = "查询用户的对应id主键", required = true) String id,
    @ApiParam(name = "用户名", value = "用户名称") String name) {
    return name + "：" + id;
}

在swagger-ui中显示效果

6.4.ApiIgnore

@ApiIgnore用于方法或类或参数上，表示这个方法或类被忽略。这个注解是Swagger内置的注解。

6.5.ApiImplicitParam

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

name：属性名

value：描述

required：是否是必须的

paramType：属性类型

dataType：数据类型

多个参数使用@ApiImplicitParams注解包裹@ApiImplicitParam注解

@RequestMapping(value = "getUser", method = RequestMethod.POST)
@ResponseBody
@ApiImplicitParams(value = {
    @ApiImplicitParam(name = "address", value = "用户地址", required = true, paramType = "query", dataType = "string"),
    @ApiImplicitParam(name = "name", value = "用户名称", required = true, paramType = "query", dataType = "string")
})
public User getUser(String id, String address, String name) {
    try {
        return new User("stonebridge", Integer.valueOf(id), 18, address);
    } catch (Exception e) {
        return new User("stonebridge", 7, 18, address);
    }
}

6.6.ApiModel

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

ApiModel - 描述一个实体类型。这个实体类型如果成为任何一个生成api帮助文档方法的，返回值类型的时候，此注解被解析。

value：名称

description：描述

代码示例：

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "用户", description = "封装用户的用户信息")
public class User {
	……
}

6.7.ApiModelProperty

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

value：描述

name：重写属性名

required：是否是必须的

example：示例内容

hidden：是否隐藏。

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "用户", description = "封装用户的用户信息")
public class User {
    @ApiModelProperty(value = "姓名", name = "name", required = true, example = "张三")
    private String name;
    @ApiModelProperty(value = "用户id", name = "id", required = true, example = "1")
    private Integer id;
    @ApiModelProperty(value = "用户年龄", name = "age", required = true, example = "19")
    private Integer age;
    @ApiModelProperty(value = "用户地址", name = "address", required = true, example = "宾夕法尼亚大道")
    private String address;
}

swagger-ui.html效果展示

肥电

关注

1
点赞
踩
1

收藏

觉得还不错? 一键收藏
0
评论
swagger2

1.Swagger简介1.1.前言接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要，但是由于项目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际情况不一致。很多人员会抱怨别人写的接口文档不规范，不及时更新。但是当自己写的时候确实最烦去写接口文档。这种痛苦只有亲身经历才会牢记于心。如果接口文档可以实时动态生成就不会出现上面问题。Swagger可以完美的解决上面的问题。1.2.Open API是什么Open API规范(
复制链接

扫一扫