swagger详解(全)

已于 2024-02-20 15:45:50 修改
阅读量1.1w 收藏 122
点赞数 20
文章标签： java swagger
于 2020-04-07 00:56:58 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/qq_21561501/article/details/105328931
版权

swagger用处

swagger引入坐标

swagger编写配置类

swagger注解引入Controller类（类与方法）

swagger注解引入Controller类（非实体请求参数）

swagger注解引入Controller类（实体请求参数）

swagger注解引入实体类

swagger自定义启用

swagger自定义分组

swagger注解

swagger用处

swagger用于自动生成接口文档，API始终保持同步，脱离PostMan测试接口。正式发布时需关闭swagger，出于安全考虑且节省运行的内存。

访问路径： http://localhost:8080/swagger-ui.html

swagger引入坐标

springboot集成swagger需要引入以下两个包

<!-- swagger-ui -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.8.0</version>
</dependency>
<!-- swagger -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.8.0</version>
</dependency>

swagger编写配置类

用于开启swagger功能，以及设置 API 文档的基本信息和请求接口的过滤条件。

@Configuration
//开启swagger功能
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                //用于定义API主界面的信息
                .apiInfo(apiInfo())
                //用于控制接口被swagger做成文档
                .select()
                //要扫描的API(Controller)基础包
                .apis(RequestHandlerSelectors.any())
                //扫描路径选择
                .paths(PathSelectors.any())
                .build();

    }

    /**
     * 用于定义API主界面的信息
     * @return
     */
    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()
                //文档标题
                .title("自定义标题")
                //接口概述
                .description("自定义描述")
                //联系人的信息
                .contact(new Contact("联系人名称","www.ferao.com","ferao@qq.com"))
                //版本号
                .version("1.0")
                //定义服务的域名
                .termsOfServiceUrl(String.format("url"))
                //.license("LICENSE")//证书
                //.licenseUrl("http://www.guangxu.com")//证书的url
                .build();
    }

}

项目启动后，可看到项目内可调用的所有接口（无任何描述信息）

在这里插入图片描述

swagger注解引入Controller类

@RestController
@RequestMapping(value = "mode")
@Api(value = "自定义Controller", tags = "Controller标签", description = "Controller描述")
public class FeraoController {

    /**
     * @param demoParam
     * @throws IOException
     * @throws InterruptedException
     */
    @ApiOperation(value = "测试接口", notes = "测试接口注释")
    @GetMapping(value = "demoHander")
    public void demoHander(String demoParam) {

      System.out.println(demoParam);
    }
}

在这里插入图片描述

swagger注解引入Controller类（非实体请求参数）

swagger注解引入Controller类（实体请求参数）

swagger注解引入实体类

1. 只要接口中返回值存在实体类，就会被swagger扫描
2. swagger页面给实体类Moel加注释

@Data
@ApiModel(value="测试实体",description="测试实体描述")
public class DemoFormatInfo {

    @ApiModelProperty(value = "用户名",required = true,example = "root")
    private String dateMode;

    @ApiModelProperty(value = "密码",required = false,example = "123456")
    private String datePassWord;

}

在这里插入图片描述

swagger自定义启用

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${common.swagger.enable}")
    private boolean swaggerEnable;

    @Value("${common.swagger.title}")
    private String title;

    @Value("${common.swagger.description}")
    private String description;

    @Value("${common.swagger.author}")
    private String author;

    @Value("${common.swagger.url}")
    private String url;

    @Value("${common.swagger.mail}")
    private String mail;

    @Value("${common.swagger.version}")
    private String version;

    @Bean
    public Docket api() {

        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerEnable)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();

    }

    /**
     * 用于定义API主界面的信息
     * @return
     */
    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .contact(new Contact(author,url,mail))
                .version(version)
                .termsOfServiceUrl(String.format("url"))
                //.license("LICENSE")//证书
                //.licenseUrl("http://www.guangxu.com")//证书的url
                .build();
    }

}

common:
  swagger:
    enable: true
    title: "PERSONAL MODULE"
    description: "A project based on hobbies"
    author: "ferao"
    url: "www.ferao.com"
    mail: "ferao@qq.com"
    version: "1.0"

swagger自定义分组

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${common.swagger.enable}")
    private boolean swaggerEnable;

    @Value("${common.swagger.title}")
    private String title;

    @Value("${common.swagger.description}")
    private String description;

    @Value("${common.swagger.author}")
    private String author;

    @Value("${common.swagger.url}")
    private String url;

    @Value("${common.swagger.mail}")
    private String mail;

    @Value("${common.swagger.version}")
    private String version;

    @Bean
    public Docket api1() {

        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerEnable)
                .groupName("ModelOne")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();

    }

    @Bean
    public Docket api2() {

        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerEnable)
                .groupName("ModelTWO")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();

    }

    /**
     * 用于定义API主界面的信息
     * @return
     */
    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .contact(new Contact(author,url,mail))
                .version(version)
                .termsOfServiceUrl(String.format("url"))
                //.license("LICENSE")//证书
                //.licenseUrl("http://www.guangxu.com")//证书的url
                .build();
    }

}

在这里插入图片描述

swagger注解

注解作用位置 示例
@EnableSwagger2启用 Swagger 功能
@Api修饰整个类，描述Controller的作用 @Api(value = “app端用户登录”, tags = “ap_user”, description = “app端用户登录API”)
@ApiOperation描述Controller中的接口 @ApiOperation(“用户登录”)
@ApiParam单个参数的描述信息
@ApiModel用对象来接收参数
@ApiModelProperty用对象接收参数时，描述对象的一个字段 @ApiModelProperty(value = “手机号”,required = true) private String phone;
@ApiResponseHTTP响应其中1个描述
@ApiResponsesHTTP响应整体描述
@ApiIgnore使用该注解忽略这个API
@ApiError发生错误返回的信息
@ApiImplicitParam一个请求参数
@ApiImplicitParams多个请求参数的描述信息

进阶配置：扫描接口

@Bean
public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否启动swagger 如果是false则不能在浏览器中使用
                .enable(true)
                .select()
                //RequestHandlerSelectors. 配置要扫描的方式
                //basePackage():指定要扫描的包
                //any():扫描全部
                //none()：不扫描
                //withClassAnnotation():扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation():扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.ferao.controller"))
                //.paths() .过滤URL
                //any() 任何请求都扫描
                //none() 任何请求都不扫描
                //ant()	通过ant控制
                //regex() 通过正则表达式控制
                .paths(PathSelectors.ant("/ferao/**"))
                .build();
 }

请求接口名称描述

@ApiOperation(value = "1.根据全局变量获得author")
	   @GetMapping("/user")
	   public String getUsers(ModelMap modelMap){
	       System.out.println(modelMap.get("author"));
	       return "User-Messege";
	   }

效果图示例
在这里插入图片描述

请求接口参数描述

@ApiOperation(value = "1.根据全局变量获得author")
@ApiImplicitParams({
        @ApiImplicitParam(name = "name", value = "名称", required = true, paramType = "query", dataType = "String")
})
@GetMapping("/user")
public String getUsers(String name){
    return "User-Messege";
}

效果图示例

在这里插入图片描述

Responses返回类型描述

@ApiOperation(value = "1.根据全局变量获得author") 
@ApiImplicitParams({
     @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "名称", required = true, paramType = "query", dataType = "String")
    })
})
@ApiResponses({
        @ApiResponse(code=200,message="请求成功"),
        @ApiResponse(code=500,message="系统异常")
})
@GetMapping("/user")
public String getUsers(String name){
    return "User-Messege";
}

[注]
paramType=“body” 代表参数应该放在请求的什么地方：
header–>放在请求头。请求参数的获取：@RequestHeader(代码中接收注解)
query–>用于get请求的参数拼接。请求参数的获取：@RequestParam(代码中接收注解)
path（用于restful接口）–>请求参数的获取：@PathVariable(代码中接收注解)
body–>放在请求体。请求参数的获取：@RequestBody(代码中接收注解)
form（不常用）
dataType=“int” 代表请求参数类型为int类型，当然也可以是Map、User、String等；

Ferao
关注
Swagger工具详解
Judy-命中注定与众不同
12-13 5577
前言小编前几天在学习了Swagger，一直都处于迷迷糊糊的，不太明白他的优势，单纯的认为只是提供给我们一个界面用于前后台的交互，其实还有很多其他的功能What Swaggerswagger表示用于前后端分离，接口管理和测试工具集，Swagger规范定义了一系列的文件，用以描述API，这些文件被Swagger-ui显示用于展示API，也可以用于被Swagger-Codegen项目用于生产代码，我们使用
Swagger快速入门
maoheguxiang的博客
03-01 96
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(它的主要作用是：使得前后端分离开发更加方便，有利于团队协作接口的文档在线自动生成，降低后端开发人员编写接口文档的负担功能测试Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，即可非常简单快捷的使用Swagger。
Swagger简介以及SpringBoot整合Swagger（通俗易懂）
BookSea的博客
10-22 2517
1.Swagger简介 2.SpringBoot整合Swagger 文章目录前言一、Swagger简介二、SpringBoot整合Swagger1.引入库2.读入数据总结 前言 在服务端开发过程中，开发人员往往会提供出来很多API接口供客户端开发人员使用，那么为了方便使用呢，开发人员会在开发接口的过程中同时维护一份文档，以说明每一个接口的访问方式、需要的参数、返回的结果等基本信息。 基于上述情况，诞生了许多API接口文档自动化生成工具，今天重点要说的就是其中的Swagger。 一、Swagger简
Swagger | 十分钟开启swagger大师生涯
最新发布
赵同学的博客
07-09 1279
前后端分离前端 -> 前端控制层、视图层后端 -> 后端控制层、服务层、数据访问层前后端通过API进行交互前后端相对独立且松耦合产生的问题前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发解决方案首先定义schema [ 计划的提纲 ]，并实时跟踪最新的API，降低集成风险Swagger号称世界上最流行的API框架Restful Api 文档在线自动生成器 =>API 文档 与API 定义同步更新直接运行，在线测试API。
Swagger（全） SpringBoot整合与使用
Hello World!
04-22 4699
Swagger 首先是一个规范、完整和统一的接口文档维护规范/标准。在这个标准下，Swagger官方提供了很多基于该标准的自动化接口维护工具，用于生成、描述、调用和可视化接口文档的Web 服务。
后端 API 接口文档 Swagger 使用指南
诗诗的远方
05-30 6074
swagger作为一款辅助性的工具，能大大提升我们的和前端的沟通效率,接口是一个非常重要的传递数据的媒介，每个接口的签名、方法参数都非常重要。一个良好的文档非常重要，如果采用手写的方式非常容易拼写错误，而swagger可以自动化生成参数文档，这一切都加快了我们的沟通效率。并且可以替代postman的作用。实在是开发编程必备良品啊。
SpringBoot集成Swagger终极版
不言而喻i的博客
06-03 6886
学习目标： 了解Swagger的概念及作用 掌握在项目中集成Swagger自动生成API文档 Swagger简介 前后端分离 前端 -> 前端控制层、视图层 后端 -> 后端控制层、服务层、数据访问层 前后端通过API进行交互 前后端相对独立且松耦合 产生的问题 前后端集成，前端或者后端无法做到“及时协商，尽早解决”，最终导致问题集中爆发 解决方案 首先定义schema [ 计划的提纲 ]，并实时跟踪最新的API，降低集成风险 Swagger 号称世界上最流行的API框.
Swagger简介
热门推荐
Ghost Stories
03-22 26万+
欢迎访问本人博客：http://wangnan.tech   欢迎关注简书：    点击打开链接   欢迎关注微信公众号： 前言 Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。 Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视...
Swagger详解
qq_39594407的博客
02-10 2083
十分钟快速了解swagger2
swagger详细讲解
qq_32861259的博客
04-28 449
Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。相较于传统的Postman或Curl方式测试接口，使用swagger简直就是傻瓜式操作，不需要额外说明文档(写得好本身就是文档)而且更不容易出错，只需要录入数据然后点击Execute，如果再配合自动化框架，可以说基本就不需要人为操作了。1、默认的 访问 http://localhost:8080/swagger-ui.html。
Swagger详解（SpringBoot Swagger集成）.docx
06-27
Swagger 是一个强大的工具，用于构建、管理和维护 RESTful 风格的 Web 服务。它遵循 OpenAPI 规范，提供了全面的框架，包括生成 API 文档、接口测试和可视化的功能。Swagger 的核心目标是确保客户端和服务器的同步...
Springboot集成Swagger详解经过
12-21
在本文中，我们将深入探讨如何在Spring Boot应用中集成Swagger，并详细解析集成过程及关键配置。Swagger是一款强大的API文档工具，它可以自动生成RESTful API的文档，帮助开发者更轻松地管理和测试API。以下是对...
.Net Core2.1 WebAPI新增Swagger插件详解
01-01
Swagger是一个WebAPI在线注解、调试插件，过去我们主要通过手工撰写WebAPI接口的交互文档供前端开发人员或外部开发者， 官网地址：https://swagger.io/。 但是在实际工作中，往往咋们的文档工作通常落后于实际的环境...
Swagger详解（SpringBoot+Swagger集成）
ai_miracle的博客
09-14 4万+
Swagger-API文档接口引擎 Swagger是什么 Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。 在项目开发中，根据业务代码自动生成API文档，给前端提供在线测试，自动显示JSON格式，方便了后...
swagger详解
weixin_30653023的博客
07-31 110
1快速环境搭建 pom.xml文件中添加如下内容(看清楚再复制，此处不是全部内容) 1 <properties> 2 ... 3 <swagger.version>2.2.2</swagger.version> 4 ... 5 </properties> ...
Swagger注解详解
御良私塾
08-08 643
Swagger注解详解
【Swagger】常用注解及具体实例（超全）
A minor
01-29 1万+
在上一篇我们详细的介绍了使用 Swagger 时需要做的配置，现在已经能得到一个我们自己想要的页面了 但是，这也看不明白啊。。。接口连个中文说明都没有。。。所以，Swagger 提供了很多注解，就是让我们去为每个类、每个接口/参数、每个Model 写解释说明的。 1.用于类的注解 @Api：资源描述 标识这个类是 Swagger 的资源， @Api(tags = "商户相关接口") @RestController @RequestMapping("/merchants") public class Mer
spring boot整合swagger使用教程详解
09-07
Spring Boot是一个开源的Java开发框架，而Swagger是一个用于构建、发布、文档化和管理API的工具。下面详细介绍如何在Spring Boot中整合Swagger。 首先，你需要在pom.xml文件中添加Swagger的依赖项。在<dependencies>标签中添加以下代码： ```xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.10.5</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.10.5</version> </dependency> ``` 然后，你需要在Spring Boot的配置类中添加相关的注解和配置。创建一个SwaggerConfig.java文件，添加以下代码： ```java @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("your.package.name")) .paths(PathSelectors.any()) .build(); } @Bean public UiConfiguration uiConfig() { return new UiConfiguration(null, "list", "alpha", "schema", UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS, false, true, 60000L); } } ``` 在上面的代码中，你需要将"your.package.name"替换为你的应用程序的包名。这将扫描该包下的所有控制器，生成API文档。 接下来，你可以启动你的Spring Boot应用程序，并访问"http://localhost:8080/swagger-ui.html"来查看生成的API文档。你将看到所有的控制器和它们的方法以及相关的参数和注释。 如果你想修改API的文档信息，你可以使用Swagger中的注解来添加说明和标注。例如，你可以在控制器的方法上添加@ApiOperation注解来描述该方法的作用。 综上所述，将Swagger整合到Spring Boot中是很简单的。你只需要添加依赖项，配置SwaggerConfig类，然后访问Swagger UI来查看生成的API文档。同时，你可以使用Swagger注解来进一步完善API文档。希望这个教程可以帮助你理解如何在Spring Boot中使用Swagger。
评论 4
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值