Swagger教程

这篇具有很好参考价值的文章主要介绍了Swagger教程。希望对大家有所帮助。如果存在错误或未考虑完全的地方,请大家不吝赐教,您也可以点击"举报违法"按钮提交疑问。

Swagger

目标

Swagger简介【了解】

Springboot整合swagger【掌握】

Swagger 常用注解【掌握】

一、Swagger简介

​ Swagger 是一系列 RESTful API 的工具,通过 Swagger 可以获得项目的⼀种交互式文档,客户端 SDK 的自 动生成等功能。

​ Swagger 的目标是为 REST APIs 定义一个标准的、与语⾔言无关的接口,使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下,能发现和理解各种服务的功能。当服务通过 Swagger 定义,消费者就能与远程的服务互动通过少量的实现逻辑。Swagger(丝袜哥)是世界上最流行的 API 表达工具。

二、Springboot整合swagger

​ 使用 Spring Boot 集成 Swagger 的理念是,使用用注解来标记出需要在 API 文档中展示的信息,Swagger 会根据项目中标记的注解来生成对应的 API 文档。Swagger 被号称世界上最流行的 API 工具,它提供了 API 管理的全套解决方案,API 文档管理需要考虑的因素基本都包含,这里将讲解最常用的定制内容。

1、添加swagger坐标

Spring Boot 集成 Swagger 3 很简单,需要引入依赖并做基础配置即可。

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

2、Swagger Helloword 实现

2.1、创建springboot项目

在启动类上加上@EnableOpenApi 注解 启用swagger api文档功能

@SpringBootApplication
@EnableOpenApi  //启动swagger api文档注解
public class SwaggerApplication {
}
2.2、写一个接口
@RestController
public class SwaggerController {

    @RequestMapping("/hello")
    public String getInfo(String par){
        return par;
    }
}
2.2、访问地址
http://localhost:8080/swagger-ui/index.html

Swagger教程

三、常用的配置注解

​ Swagger 通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息等

1、Api 注解和 ApiOperation 注解

  • @Api

    使用在类上,表明是swagger资源,@API拥有两个属性:value、tags。

    生成的api文档会根据tags分类,直白的说就是这个controller中的所有接口生成的接口文档都会在tags这个list下;tags如果有多个值,会生成多个list,每个list都显示所有接口

    value的作用类似tags,但是不能有多个值

    语法:
      @Api(tags = "用户操作")
      或
      @Api(tags = {"用户操作","用户操作2"})
    
  • @ApiOperation

    使用于在方法上,表示一个http请求的操作

    语法:
        @ApiOperation(value = "", 
                      notes = "", 
                      response = )
    属性说明:
      value:方法说明标题
      notes:方法详细描述
      response:方法返回值类型
    

    案例:使用@Api和@ApiOperation生成api文档

    @RestController
    @Api(tags = {"hello请求","用户操作"})
    public class SwaggerController {
    
        @RequestMapping("/hello")
        @ApiOperation(value = "swagge请求",
                      notes = "第一个swagger请求",
                        response = String.class
    
        )
        public String getInfo(String param){
            return param;
        }
    }
    

2、ApiImplicitParams 注解和 ApiImplicitParam

@ApiImplicitParams 注解和 @ApiImplicitParam 用于对方法中的非对象参数(参数绑定到简单类型时使用。)进行说明

语法:
@ApiImplicitParams(value = {
     @ApiImplicitParam(name="", value = "", type = "", required = true, paramType = "", defaultValue  = "")
})

属性说明:
    name:形参名称
    value:形参的说明文字
    type:形参类型
    required:该参数是否必须  true|false
    paramType: 用于描述参数是以何种方式传递到 Controller 的,它的值常见有: path, query, body 和 header 
        path 表示参数是『嵌在』路径中的,它和 @PathVariable 参数注解遥相呼应;
    	query 表示参数是以 query string 的形式传递到后台的(无论是 get 请求携带在 url 中,还是 post 请求携带在请求体中),它和 @RequestParam 参数注解遥相呼应;
    	header 表示参数是『藏在』请求头中传递到后台的,它和 @RequestHeader 参数注解遥相呼应的。
    	form 不常用.
    defaultValue :参数默认值

注意:@ApiImplicitParam 的 name 属性要和 @RequestParam 或 @PathVariable 的 value 遥相呼应。

案例:使用@ApiImplicitParams注解和 @ApiImplicitParam 对方法参数进行说明

@RestController
@Api(tags = {"hello请求","用户操作"})
public class SwaggerController {

    @RequestMapping("/hello")
    @ApiOperation(value = "swagge请求",
                  notes = "第一个swagger请求",
                    response = String.class
    )
    @ApiImplicitParams(value ={
            @ApiImplicitParam(name="param",
                    value = "参数名",
                    type = "String",
                    required = true,
                    paramType = "query",
                    defaultValue  = "1" )
    })
    public String getInfo(String param){
        return param;
    }
}

3、ApiModel注解和 ApiModelProperty

  • @ApiModel

    用在实体类上,表示对类进行说明,用于实体类中的参数接收说明。

    语法:
        @ApiModel("用户类")
        public class Users {
        }
    
  • @ApiModelProperty

    用于对实体类中的属性进行说明

    @ApiModel("用户类")
    @Data
    public class Users {
    
        @ApiModelProperty(value = "编码:主键")
        private Integer id;
    
        @ApiModelProperty(value = "用户名")
        private String username;
    
        @ApiModelProperty(value = "密码")
        private String password;
    
    }
    

4、ApiResponse 和 ApiResponses

@ApiResponses 注解和 @ApiResponse 标注在 Controller 的方法上,用来描述 HTTP 请求的响应

/**
     * 添加用户
     *
     * @param user
     * @return
     */
    @PostMapping("/add")
    @ApiOperation(value = "添加用户",notes = "添加用户信息",response = ResponseResult.class)
    @ApiResponses({ @ApiResponse(code = 200, message = "添加成功", response = ResponseResult.class),
            	    @ApiResponse(code = 500, message = "添加失败", response = ResponseResult.class) })
    public ResponseResult<Void> addUser(@RequestBody User user) {
        //获得生成的加密盐
        user.setSalt(SaltUtils.getSalt());
        int n = userService.addUser(user);
        if (n > 0) {
            return new ResponseResult<Void>(200, "添加成功");
        }
        return new ResponseResult<Void>(500, "添加失败");
    }

5、创建 SwaggerConfig 配置类

在 SwaggerConfig 中添加两个方法:(其中一个方法是为另一个方法作辅助的准备工作)

api()方法使用 @Bean,在启动时初始化,返回实例 Docket(Swagger API 摘要对象),这里需要注意的是 .apis(RequestHandlerSelectors.basePackage("xxx.yyy.zzz")) 指定需要扫描的包路路径,只有此路径下的 Controller 类才会自动生成 Swagger API 文档。

/**
 * Swagger配置类
 */
@Configuration  //项目启动时加载此类
public class SwaggerConfig {
    
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                // 此处自行修改为自己的 Controller 包路径。
                .apis(RequestHandlerSelectors.basePackage("cn.woniu.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo(){
		return new ApiInfoBuilder()
       .title("XXX 项目接口文挡")
       .description("XXX Project Swagger2 UserService Interface")  //说明信息
       .termsOfServiceUrl("http://localhost:8080/swagger-ui/index.html") //文档生成的主页地址
       .version("1.0")  //文档版本
       .build();
    }
}

apiInfo()方法配置相对重要一些,主要配置页面展示的基本信息包括,标题、描述、版本、服务条款等,查看 ApiInfo 类的源码还会发现支持 license 等更多的配置

四、springsecurity整合swagger

4.1,配置放行的地址

  http.authorizeRequests().antMatchers( "/swagger-ui.html",
                "/swagger-ui/*",
                "/swagger-resources/**",
                "/v2/api-docs",
                "/v3/api-docs",
                "/webjars/**").permitAll()
                .anyRequest().authenticated();

4.2,替换UI

上面的整个过程已经完成了,但是生成的接口文档的页面,其实很多人不太喜欢,觉得不太符合国人的使用习惯,所有又有一些大神,提供了其他的UI测试页面。这个页面的使用还是比较广泛的。

访问地址:http://localhost:8080/doc.html文章来源地址https://www.toymoban.com/news/detail-416661.html

	<dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>swagger-bootstrap-ui</artifactId>
        <version>1.9.6</version>
    </dependency>

到了这里,关于Swagger教程的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • 在SpringBoot中通过配置Swagger权限解决Swagger未授权访问漏洞

    博主 默语带您 Go to New World. ✍ 个人主页—— 默语 的博客👦🏻 《java 面试题大全》 🍩惟余辈才疏学浅,临摹之作或有不妥之处,还请读者海涵指正。☕🍭 《MYSQL从入门到精通》数据库是开发者必会基础之一~ 🪁 吾期望此文有资助于尔,即使粗浅难及深广,亦备添少许微薄

    2024年04月23日
    浏览(39)
  • SpringBoot整合Swagger2

    在团队开发中,一个好的 API 文档不但可以减少大量的沟通成本,还可以帮助一位新人快速上手业务。传统的做法是由开发人员创建一份 RESTful API 文档来记录所有的接口细节,并在程序员之间代代相传。这种做法存在以下几个问题: 1)API 接口众多,细节复杂,需要考虑不同

    2023年04月16日
    浏览(35)
  • SpringBoot 整合Swagger2

    Swagger是一套开源工具和规范,用于设计、构建和文档化 RESTful Web 服务。它允许开发人员定义API的各个方面,并生成易于理解的API文档和交互式API探索界面。同时,Swagger还提供代码生成工具,可自动生成与API交互的客户端和服务器端代码,提高开发效率。 官网:https://swagge

    2024年04月27日
    浏览(32)
  • springboot 整合swagger 入门 使用

    一定要看好版本。 Springboot ✚ Swagger各版本整理_swagger版本_qq_33334411的博客-CSDN博客 我的版本: 新建一个boot web项目之后,导入上述依赖。 在confi包下新建一个SwaggerConfig.java配置类 Swgger2Config.java 在controller包新建HelloController.java 在modle.vo下新建HelloVO.java 在 application.yml/properties 文

    2024年02月12日
    浏览(36)
  • 【Swagger】常用注解的使用、SpringBoot的整合及生产环境下屏蔽Swagger

            Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。它使得部署管理和使用功能强大的API从未如此简单。Swagger让文件的方法、参数和模型紧密集成到服务器端的代码,允许API始终保持同步。 在软件开发中,常用注解(Annotation)主

    2024年02月03日
    浏览(38)
  • swagger使用教程——快速使用swagger

    一、swagger简介 官网:https://swagger.io/ 1、认识swagger swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RestFul风格的web服务,总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器断的代码,允许API来始终保持

    2023年04月23日
    浏览(38)
  • 【Springboot系列】Springboot整合Swagger3不简单

       Swagger是一个根据代码注解生成接口文档的工具,减少和前端之间的沟通,前端同学看着文档就可以开发了,提升了效率,之前很少写swagger,这次自己动手写,还是有点麻烦,不怎么懂,记录下,避免下次继续踩坑         新建一个springboo项目,一路next就好,这里使用的

    2024年02月05日
    浏览(38)
  • 【解决问题】在SpringBoot中通过配置Swagger权限解决Swagger未授权访问漏洞

    Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。其中,Swagger-UI会根据开发人员在代码中的设置来自动生成API说明文档。若存在相关的配置缺陷,攻击者可以在未授权的状态下,翻查Swagger接口文档,得到系统功能API接口的详细参数,再

    2024年02月02日
    浏览(42)
  • SpringBoot——Swagger2 接口规范

    优质博文:IT-BLOG-CN 如今, REST 和微服务已经有了很大的发展势头。但是, REST 规范中并没有提供一种规范来编写我们的对外 REST 接口 API 文档。每个人都在用自己的方式记录 api 文档,因此没有一种标准规范能够让我们很容易的理解和使用该接口。我们需要一个共同的规范和

    2024年02月04日
    浏览(45)
  • springboot 集成 Swagger3(速通)

    → springboot 集成 Swagger2 ← 这次直接使用 2.5.6 的 spring-boot 。 依赖: 启动类加注解 @EnableOpenApi 新建测试类 访问 http://127.0.0.1:8080/swagger-ui.html ,没错,又是 Error 页面 此部分参考:https://blog.csdn.net/mmmm0584/article/details/117786055 在swagger3.0中,swagger-ui.html的位置发生了变化:   

    2024年02月03日
    浏览(37)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包