Swagger基础与应用

最新推荐文章于 2024-07-31 09:32:30 发布

你眼里的星星不是我

最新推荐文章于 2024-07-31 09:32:30 发布

阅读量309

点赞数 1

分类专栏： java 文章标签： swagger2 api 前端后端 restful

本文链接：https://blog.csdn.net/qq_46108602/article/details/115582540

版权

java 专栏收录该内容

4 篇文章 0 订阅

订阅专栏

1、Swagger简介

1.1、Swagger作用

自动生成API文档，方便前后端分离开发相对独立且进行交互。

1.2、前后端分离

前端 -> 前端控制层、视图层
后端 -> 后端控制层、服务层、数据访问层
前后端通过API进行交互
前后端相对独立且松耦合

1.3、相关问题

前后端分离，如何知道对方的请求地址以及参数要求呢？

如果修改API文档不及时会导致对方不知道修改相应位置，怎么解决？

=====> 前端或者后端无法做到“及时协商，尽早解决”

1.4、解决方案

使用跟随代码同步变化的API文档工具------Swagger

1.5、Swagger框架

号称世界上最流行的API框架
Restful Api 文档在线自动生成器 => API 文档跟随代码同步更新
直接运行，在线测试API
支持多种语言（如：Java，PHP等）
官网：https://swagger.io/

2、Springboot环境下的Swagger

2.1、Swagger的导入

SpringBoot集成Swagger => springfox，两个jar包

Springfox-swagger2
springfox-swagger-ui

1、使用idea先新建springboot项目，项目名称为：Swagger，jdk版本为1.8.

2、在pom文件中导入Swagger相关依赖:

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

2.2、测试Swagger环境

1、编写MyController，测试项目正常运行！

package com.example.controller;

import com.example.anno.MyAnnotationSwagger;
import com.example.pojo.MyPojo;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

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

    @GetMapping("/testPojo")
    public MyPojo testPojo(){
        return new MyPojo();
    }

    @GetMapping("/test")
    public String test(){
        return "test";
    }

    @GetMapping("/get")
    public String get( String a,String b){
        return "get";
    }

    @PostMapping("/post")
    public String post(String a,String b){
        return "post";
    }

    @MyAnnotationSwagger
    @RequestMapping("/req")
    public String req(String m){
        return "req";
    }

2、使用Swagger，可以先编写一个Swagger的相关配置注解：@MyAnnotationSwagger

//@Target:描述当前注解可以定义在什么资源上，METHOD（方法），TYPE（类型），FIELD（属性），PARAMETER(方法参数)
//@Retention:当前注解在什么时候有效
@Target(value={ElementType.METHOD,ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotationSwagger {
    //自定义注解中的属性，相当于@MyAnnotationSwagger(value="")
    String value() default "";
}

3、测试Swagger，访问呢Localhost:8080/swagger-ui.html.

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-0GWUGGYk-1618053427897)(G:\自学笔记\笔记图片\1618047242(1)].png)

2.3、Swagger配置

编写配置文件SwaggerConfiguration

1、Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

/**
     * 创建Docket类型的对象，并使用spring容器管理
     * Docket是swagger中的全局配置对象
     * @return
     */
@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2);
}

2、Swagger配置信息

@Bean
    public Docket docket(){
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        //API帮助文档的描述信息。
        ApiInfo apiInfo = new ApiInfoBuilder()
                .contact(//配置swagger文档主题内容 name：文档发布者的名称，url：文档发布者的网站地址，email：文档发布者的电子邮箱
                        new Contact("swagger示例文档","http://www.example.com","admin@qq.com")
                )
                .title("swagger框架学习示例文档")
                .description("swagger框架学习帮助文档详细描述")
                .version("1.1")
                .build();
        //给docket上下文配置api描述信息
        docket.apiInfo(apiInfo);
        docket = docket
                .select()//获取docket中的选择器，返回值为ApiSelectorBuilder。构建选择器，如：扫描什么包的注解
                .apis(
                        Predicates.not(//取反
                                RequestHandlerSelectors.withMethodAnnotation(//当方法上有注解的时候返回true
                                        MyAnnotationSwagger.class//当方法上有MyAnnotationSwagger注解的时候返回true
                                )
                        )
                )
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))//设定扫描哪个包及其子包
                .paths(
                        Predicates.or(//多个规则符合一个即可，请求路径规则
                            PathSelectors.regex("/swagger/.*"),//使用正则表达式约束生成api文档的路径地址
                            PathSelectors.regex("/swagger2/.*"),
                                PathSelectors.regex("/.*")
                        )
                )
                .build();//重新构建docket对象

        return docket;
    }

3、重启项目，访问测试 localhost:8080/swagger-ui.html

3、Swagger相关注解

3.1、@Api注解

@Api注解：描述当前类型生成帮助文档的信息

属性：

 -tags： 给当前类型定义别名，可以有多个。定义几个别名，在ui视图中就显示几个控制器访问菜单。

 -description： 给当前类型生成的帮助文档生成一个描述信息（已过时！）

@RestController
@RequestMapping("/swagger")
@Api(tags = {"MyController","Swagger学习示例控制器"},description = "测试API类型描述信息")
public class MyController {
    ---各种请求列表---
}

3.2、@ApiOperation注解

@ApiOperation：给方法添加描述信息。

    @GetMapping("/get")
    @ApiOperation(value = "get方法，执行get操作",notes = "swagger学习使用发get请求处理方法")
    public String get(String a, String b){
        return "get";
    }

3.3、@ApiParam注解

@ApiParam：给参数添加描述信息。

    @GetMapping("/get")
    @ApiOperation(value = "get方法，执行get操作",notes = "swagger学习使用发get请求处理方法")
    public String get(
            @ApiParam(name = "用户名（a）",value = "用户名参数描述",required = true) String a,
            @ApiParam(name = "密码(b)",value = "密码参数描述",required = true) String b){
        return "get";
    }

3.4、@ApiIgnore注解

@ApiIgnore: 忽略，此注解描述的方法或类型，不生成api帮助文档

//@ApiIgnore: 忽略，此注解描述的方法或类型，不生成api帮助文档
    @ApiIgnore
    @PostMapping("/post")
    public String post(String a,String b){
        return "post";
    }

3.5、@ApiImplicitParams注解

1、@ApiImplicitParam：标注一个参数。

@GetMapping("/test")
    @ApiImplicitParam(name = "m",value = "m参数描述",required = false,paramType = "字符串",dataType = "键值对")
public String test(String m,String n){
        return "test";
    }

2、@ApiImplicitParams：可标注所有参数。

@GetMapping("/test")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "m",value = "m参数描述",required = false,paramType = "字符串",dataType = "键值对"),
            @ApiImplicitParam(name = "n",value = "n参数描述",required = true,paramType = "字符串(String)",dataType = "键值对")
    })
    public String test(String m,String n){
        return "test";
    }

3.6、@ApiModel注解

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

注解@ApiModel和注解@ApiModelProperty都用于实体类上，给实体类添加描述。

@ApiModel为类添加注释
@ApiModelProperty为类的属性添加注释

实体类MyPojo：

/**
 * @ApiModel:描述实体类类型，这个实体类如果成为任何一个生成api帮助文档方法的返回值类型的时候
 * 此注解会被解析
 */
@ApiModel(value = "自定义实体MyPojo",description = "MyPojo存储用户数据")
public class MyPojo implements Serializable {

    @ApiModelProperty(value = "主键",name = "主键(id)",required = false,example = "1",hidden = false)
    private Integer id;
    @ApiModelProperty(value = "姓名",name = "姓名(name)",required = true,example = "admin",hidden = false)
    private String name;
    @ApiModelProperty(value = "密码",name = "密码(password)",required = true,example = "admin",hidden = false)
    private String password;

    public MyPojo() {
    }
    public Integer getId() {
        return id;
    }
    public void setId(Integer id) {
        this.id = id;
    }
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public String getPassword() {
        return password;
    }
    public void setPassword(String password) {
        this.password = password;
    }
}

controller发起请求，返回值为此实体类。

@GetMapping("/testPojo")
    public MyPojo testPojo(){
        return new MyPojo();
    }

重启项目，ui界面下方的model模块可以显示实体类信息。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-P1OGBW67-1618053427900)(C:\Users\gaozh\AppData\Roaming\Typora\typora-user-images\image-20210410185147333.png)]

4、Swagger-ui界面

不同的ui界面是根据导入的不同的Swagger-ui包来决定的。

4.1、默认ui界面

<dependency> 
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

注：访问ui界面：localhost:8080/swagger-ui.html

4.2、bootstrap-ui界面

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.1</version>
</dependency>

注：访问ui界面：localhost:8080/doc.html

4.3、Layui-ui界面

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
    <groupId>com.github.caspar-chen</groupId>
    <artifactId>swagger-ui-layer</artifactId>
    <version>1.1.3</version>
</dependency>