Swagger

最新推荐文章于 2024-03-22 17:48:37 发布

Healerjy

最新推荐文章于 2024-03-22 17:48:37 发布

阅读量157

点赞数

文章标签： spring boot java restful

本文链接：https://blog.csdn.net/Healerjy/article/details/130755659

版权

1、Swagger

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测

swagger官网地址：https://swagger.io/

1.1、Swagger 的优势

支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术
提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口

1.2、在SpringBoot中集成Swagger

实现步骤：

创建一个SpringBoot的Web项目

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-qfGdVZ4t-1684416211969)(SpringBoot.assets\image-20220401101556577-16487793582701.png)]

导入相关依赖 swagger2 swagger-ui

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

编写Controller 测试项目是否创建成功

package com.gjy.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {
    @RequestMapping("/hello")
    public String hello(){
        return "Hello Swagger";
    }
}

配置Swagger==》SwaggerConfig

package com.gjy.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2   //开启Swagger2
public class SwaggerConfig {

}

运行测试输入http://localhost:8080/swagger-ui.html

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-AydAspDh-1684416211970)(SpringBoot.assets\image-20220401104624206-16487811860122.png)]

1.3、Swagger配置

完整配置代码：

package com.gjy.config;

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

import java.util.ArrayList;

@Configuration
@EnableSwagger2   //开启Swagger2
public class SwaggerConfig {
    //配置Swagger的bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    //配置Swagger信息 apiInfo
    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("gjy", "www.gjyblogs.com", "1228981@qq.com");
        return new ApiInfo(
            "我的Swagger API文档",
            "Java是世界上最好的编程语言",
            "v1.0",
            "www.gjyblogs.com",
            contact,
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList()
        );
    }
}

测试结果如下图

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-lfb8oLY1-1684416211971)(SpringBoot.assets\image-20220401110725329-16487824469373.png)]

1.4、Swagger配置扫描接口

代码实现：

package com.gjy.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2   //开启Swagger2
public class SwaggerConfig {
    //配置Swagger的bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors配置扫描接口的方式
            //basePackage指定要扫描的包
            //any()扫描全部
            //none()不扫描
            //withClassAnnotation():扫描类上的注解   参数是一个注解的反射对象
            //withMethodAnnotation():扫描方法上的注解
            .apis(RequestHandlerSelectors.basePackage("com.gjy.controller"))
            //paths() 过滤路径
            .paths(PathSelectors.ant("/gjy/**"))
            .build()
            ;
    }

    //配置Swagger信息 apiInfo
    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("gjy", "www.gjyblogs.com", "1228981@qq.com");
        return new ApiInfo(
            "我的Swagger API文档",
            "Java是世界上最好的编程语言",
            "v1.0",
            "www.gjyblogs.com",
            contact,
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList()
        );
    }
}

配置是否启动Swagger

    //配置Swagger的bean实例
    //enable()是否启动swagger  如果为false,则swagger不能在浏览器中使用
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)
                ;
    }

1.5、Swagger面试题

如果只希望Swagger在生产环境的时候使用，在发布的时候不使用？

判断是否为生产环境
注入enable()

代码实现：

package com.gjy.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2   //开启Swagger2
public class SwaggerConfig {
    //配置Swagger的bean实例
    //enable()是否启动swagger  如果为false,则swagger不能在浏览器中使用
    @Bean
    public Docket docket(Environment environment) {
        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev", "pro");
        //通过environment.acceptsProfiles()方法判断是否处于特定的环境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(flag)
            .select()
            //RequestHandlerSelectors配置扫描接口的方式
            //basePackage指定要扫描的包
            //any()扫描全部
            //none()不扫描
            //withClassAnnotation():扫描类上的注解   参数是一个注解的反射对象
            //withMethodAnnotation():扫描方法上的注解
            .apis(RequestHandlerSelectors.basePackage("com.gjy.controller"))
            //paths() 过滤路径
            .paths(PathSelectors.ant("/gjy/**"))
            .build()
            ;
    }

    //配置Swagger信息 apiInfo
    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("gjy", "www.gjyblogs.com", "1228981@qq.com");
        return new ApiInfo(
            "我的Swagger API文档",
            "Java是世界上最好的编程语言",
            "v1.0",
            "www.gjyblogs.com",
            contact,
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList()
        );
    }
}

1.6、Swagger分组和接口注释

1、配置API文档的分组

.groupName("gjy")

如何配置多个API文档分组？配置多个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");
    }

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-9YkOAhAR-1684416211971)(SpringBoot.assets\image-20220401213515440-16488201172511.png)]

2、实体类配置

代码实现：

package com.gjy.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")   //对实体类的描述
public class User {
    @ApiModelProperty("用户名")  //对属性的描述
    private String username;
    @ApiModelProperty("密码")
    private String password;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-lz0X7EgY-1684416211972)(SpringBoot.assets\image-20220401222207057-16488229288072.png)]

3、接口注释

package com.gjy.controller;

import com.gjy.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.RestController;

@RestController
public class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello Swagger";
    }

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

    @ApiOperation("hello接口")  //对该接口的描述
    @PostMapping("/hello")
    public String hello(@ApiParam("用户名") String username) {  //对接口参数的描述
        return "hello" + username;
    }
}

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-8r1MClVA-1684416211973)(SpringBoot.assets\image-20220401222355513-16488230372083.png)]

总结：

我们可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息
接口文档实时更新
可以在线测试

Healerjy

关注

0
点赞
踩
1

收藏

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

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-lfb8oLY1-1684416211971)(SpringBoot.assets\image-20220401110725329-16487824469373.png)]
复制链接

扫一扫