swagger基础使用

最新推荐文章于 2024-09-30 14:28:09 发布

GooO_O

最新推荐文章于 2024-09-30 14:28:09 发布

阅读量1k

点赞数 25

分类专栏： java基础问题文章标签：状态模式

本文链接：https://blog.csdn.net/GooO_O/article/details/135328793

版权

java基础问题专栏收录该内容

36 篇文章 0 订阅

订阅专栏

swagger

简介：

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。
Swagger是什么？它能干什么？
发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。
但即便如此，对于许多开发来说，编写这个yml或json格式的描述文件，本身也是有一定负担的工作，特别是在后面持续迭代开发的时候，往往会忽略更新这个描述文件，直接更改代码。久而久之，这个描述文件也和实际项目渐行渐远，基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。

学习目标

了解Swagger的作用和概念
了解前后端分离
在SpringBoot中集成Swagger

前后端分离：

后端：后端控制层、服务层、数据访问层
前端：前端控制层、视图层
前后端如何交互？ ===〉 API
前后端相对独立，松耦合

Swagger

号称世界上最流行的api框架
RestFul Api 文档在线自动生成工具。····》 Api文档与API定义同步更新

在项目中使用Swagger需要 springbox

swagger2
ui

SpringBoot 集成 Swagger

新建项目 springboot-web项目

导入相关依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

注意

目前 swagger3.0 只导入这一个包就可以了

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

同时记得在 启动类 加上 @EnableWebMvc注解
启动类
在这里插入图片描述

（不用配置这个了spring.mvc.pathmatch.matching-strategy=ant_path_matcher）
（访问界面变成 http://localhost:8080/swagger-ui/index.html

编写一个 HELLO工程

配置Swagger ····》写个Config 文件

@Configuration
@EnableSwagger2  // 开启swagger2
public class SwaggerConfig {
}

测试运行

配置Swagger

Swagger 的 bean 实例： Docket

@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {

    // 配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    // 配置Swagger信息 apiInfo
    private ApiInfo apiInfo(){

        // 作者信息
        Contact contact = new Contact("xxx","urn:tos","xxxxx@qq.com");

        return new ApiInfo("xxx的 SwaggerAPI文档",
                "我的女孩-xxx",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

Swagger 配置扫描接口

Docket.select()
接口过滤的一些东东

// 配置了Swagger的Docket的Bean实例
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            // RequestHandlerSelectors 配置要扫描接口的方式
                // .basePackage()  指定要扫描的包
                // .any() 扫描全部的包
                // .none()  不扫描
                // .withClassAnnotation()  扫描类上的注解
                // .withMethodAnnotation()  指定方法上的注解
            .apis(RequestHandlerSelectors.basePackage("com.niu.swagger.controller"))
            // .path()   过滤路径       // 把/niu下的全给过滤掉了
            .paths(PathSelectors.ant("/niu/**"))
            .build();
}

配置是否启动的接口

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(false)  // enable 是否启动Swagger，如果为false 则Swagger 不能在浏览器中访问
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.niu.swagger.controller"))
//              .paths(PathSelectors.ant("/niu/**"))
            .build();
}

Mac端
idea中一个很好用的快捷键，自动创建对象类型和对象名。win+alt+V将自动创建一个对象和对象名。

我只希望我的 Swagger 在生产环境中使用，在发布的时候不使用

判断是不是生产环境 flag = false
注入enable（flag）

// 配置了Swagger的Docket的Bean实例
@Bean
public Docket docket(Environment environment){
    // 设置要显示的 Swagger环境
    Profiles profiles = Profiles.of("dev","test");
    // 获得项目的环境：
    // 通过 environment.acceptsProfiles()判断是否处在自己设定的环境中
    boolean flag = environment.acceptsProfiles(profiles);
    System.out.println(flag);
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(flag)  // enable 是否启动Swagger，如果为false 则Swagger 不能在浏览器中访问
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.niu.swagger.controller"))
//              .paths(PathSelectors.ant("/niu/**"))
            .build();
}

配置API文档的分组

.groupName("牛牛")

在这里插入图片描述

如何配置API文档的分组？配置多个Docket实例即可

// 既然groupname跟着Docket走，那我们想分多个组，可以增加多个Docket
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

- 默认首先出现A组

实体类配置


//@Api(注释信息)
@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    public String username;

    @ApiModelProperty("密码")
    public String password;
}

controller配置

package com.niu.swagger.controller;


import com.niu.swagger.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
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;
/**
 * 返回字符串
 * @author mac
 */

@RestController
public class HelloController {

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


    // 只要我们的接口中，返回值存在实体类，他就会被扫描到
    @PostMapping("/user")
    public User user(){
        return new User();
    }

    // 接口加个中文注释,不是放在类上的，是方法
    @ApiOperation("hello 控制类")
    @GetMapping("/hell2")
    public String hello(@ApiParam("用户名") String username){
        return "hello"+username;
    }

    // 接口加个中文注释,不是放在类上的，是方法
    @ApiOperation("Post测试")
    @PostMapping("/postt")
    public User postt(@ApiParam("用户名") User user){
        return user;
    }
}