您的位置: 首页  >  文章  >  Swagger如何在SpringBoot中使用

Swagger如何在SpringBoot中使用

分类: 文章 • 2022-07-17 19:05:45

这篇文章给大家介绍Swagger如何在SpringBoot中使用，内容非常详细，感兴趣的小伙伴们可以参考借鉴，希望对大家能有所帮助。

依赖

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

配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;

/**
 * Swagger的配置类
 * @author 陈加兵
 *
 */
@Configuration
public class SwaggerConfig{
 /**
 * 创建用户API文档
 * @return
 */
 @Bean
 public Docket createRestUserApi(){
 return new Docket(DocumentationType.SWAGGER_2)
 .groupName("user") 
 .apiInfo(apiInfo()) //api的信息
 .select()
 .apis(RequestHandlerSelectors
  .basePackage("cn.tedu.mycat.controller")) //添加包扫描
 .paths(PathSelectors.any()).build();

 }

 /**
 * 创建API信息
 */
 private ApiInfo apiInfo(){
 return new ApiInfoBuilder()
 .title("api文档的标题") //标题
 .description("api文档的描述") //描述
 .contact( //添加开发者的一些信息
  new Contact("爱撒谎的男孩", "https://chenjiabing666.github.io",
  "18796327106@163.com")).version("1.0").build();
 }

}

启动类

在springBoot的启动类上添加一个注解即可配置成功： @EnableSwagger2

访问api的路径
http://ip/projectName/swagger-ui.html

注解说明

@Api

  • 标注在类上，用来对这个类进行说明的

  • 如果想要生成文档，必须在类或者接口上标注

  • 属性如下：

属性名称 备注 默认值
value url的路径值
tags 如果设置这个值、value的值会被覆盖
description 对api资源的描述
basePath 基本路径可以不配置
position 如果配置多个Api 想改变显示的顺序位置
produces For example, “application/json, application/xml”
consumes For example, “application/json, application/xml”
protocols Possible values: http, https, ws, wss.
authorizations 高级特性认证时配置
hidden 配置为true 将在文档中隐藏

@ApiOperation

  • 用在API方法上，对该API做注释，说明API的作用

  • 不需要多讲，看源码，使用默认的value属性即可，说明该方法的作用

  • 属性如下：

value url的路径值
tags 如果设置这个值、value的值会被覆盖
notes 对api资源的描述
response 返回的对象，在文档中点击Model可以获取该配置的内容
responseContainer 这些对象是有效的 “List”, “Set” or “Map”.，其他无效
responseReference 可以不配置
httpMethod 可以接受 “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
position 如果配置多个Api 想改变显示的顺序位置
produces 同 Api中的定义
consumes 同 Api中的定义
protocols 同 Api中的定义
authorizations 同 Api中的定义
hidden 是否隐藏，true 或者false ，这个可以隐藏后台接口
code http的状态码 默认 200
extensions 扩展属性

@ApiImplicitParams

  • 用来包含API的一组参数注解，可以简单的理解为参数注解的集合声明

  • 很重要，这个注解其中包含接口入参的详细说明

  • 内容是集合

@ApiImplicitParam

用在 @ApiImplicitParams 注解中，也可以单独使用，说明一个请求参数的各个方面

详细的属性使用说明如下：

  • name ：属性的字段名称，相当于form表单中的name，这个就是入参的字段

  • dataType ：参数的类型，标识，字符串

  • value ：该参数的描述

  • required ：是否必填，布尔值

  • defaultValue ：缺省值，会在文档中缺省填入，这样更方面造数据，不需要调用接口的去填值了

  • paramType ：指定参数的入参数方式（也就是请求参数的位置），其中有四种常用的，如下：

    • query

    • path

    • body

    • form

paramType属性的详细说明

  • query ：必须要和入参的字段一样，也可以使用 @RequestParam() 指定

  • path ：用于Restful的风格的url，请求的参数写在路径上，如下：

@ApiOperation(value="根据用户Id获取用户信息",response=User.class,hidden=false)
 @ApiImplicitParams({
 @ApiImplicitParam(paramType = "path", name = "id", dataType="Integer", required = false, value = "用户的id", defaultValue = "1")
 })
 @GetMapping("/user/get/{id}")
 public Object getUser(@PathVariable("id")Integer id){
 return new User(id, "陈加兵");
 }

  • body：以流的形式提交 仅支持POST
     form：以表单的形式提交

关于Swagger如何在SpringBoot中使用就分享到这里了，希望以上内容可以对大家有一定的帮助，可以学到更多知识。如果觉得文章不错，可以把它分享出去让更多的人看到。

相关推荐