springboot集成swagger2

发布时间:2022-06-06 16:58:08 作者:yexindonglai@163.com 阅读(41)

1、新建一个springboot项目

  1. <parent>
  2. <groupId>org.springframework.boot</groupId>
  3. <artifactId>spring-boot-starter-parent</artifactId>
  4. <version>2.0.8.RELEASE</version>
  5. <relativePath/> <!-- lookup parent from repository -->
  6. </parent>
  7. <groupId>com.spring</groupId>
  8. <artifactId>springBoot-demo1</artifactId>
  9. <version>1.0-SNAPSHOT</version>
  10. <packaging>jar</packaging>
  11. <properties>
  12. <java.version>1.8</java.version>
  13. </properties>
  14. <dependencies>
  15. <dependency>
  16. <groupId>org.springframework.boot</groupId>
  17. <artifactId>spring-boot-starter</artifactId>
  18. </dependency>
  19. <dependency>
  20. <groupId>org.springframework.boot</groupId>
  21. <artifactId>spring-boot-starter-test</artifactId>
  22. <scope>test</scope>
  23. </dependency>
  24. <dependency>
  25. <groupId>org.springframework.boot</groupId>
  26. <artifactId>spring-boot-starter-web</artifactId>
  27. </dependency>
  28. </dependencies>

2、引入swagger依赖

  1. <dependency><!--添加Swagger依赖 -->
  2. <groupId>io.springfox</groupId>
  3. <artifactId>springfox-swagger2</artifactId>
  4. <version>2.7.0</version>
  5. </dependency>
  6. <dependency><!--添加Swagger-UI依赖 -->
  7. <groupId>io.springfox</groupId>
  8. <artifactId>springfox-swagger-ui</artifactId>
  9. <version>2.7.0</version>
  10. </dependency>

3、添加swagger配置类

  1. package com.bizzan.bitrade.config;
  2. import org.springframework.context.annotation.Bean;
  3. import org.springframework.context.annotation.Configuration;
  4. import springfox.documentation.builders.PathSelectors;
  5. import springfox.documentation.builders.RequestHandlerSelectors;
  6. import springfox.documentation.service.ApiInfo;
  7. import springfox.documentation.service.Contact;
  8. import springfox.documentation.spi.DocumentationType;
  9. import springfox.documentation.spring.web.plugins.Docket;
  10. import springfox.documentation.swagger2.annotations.EnableSwagger2;
  11. import java.util.ArrayList;
  12. @Configuration //配置类
  13. @EnableSwagger2// 开启Swagger2的自动配置
  14. public class SwaggerConfig {
  15. @Bean
  16. public Docket docket() {
  17. // 设置要显示swagger的环境
  18. // 通过 enable() 接收此参数判断是否要显示
  19. return new Docket(DocumentationType.SWAGGER_2)
  20. .apiInfo(apiInfo())
  21. // .enable(false) //配置是否启用Swagger,如果是false,在浏览器将无法访问
  22. .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
  23. // .apis(RequestHandlerSelectors.basePackage("com.bizzan.bitrade.service")) // 扫描指定包下的接口
  24. .apis(RequestHandlerSelectors.any()) // 扫描所有接口
  25. //配置你想在那个controller层生产接口文档 any()表示扫描所有
  26. .paths(PathSelectors.any())
  27. // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
  28. .build();
  29. }
  30. //配置文档信息
  31. private ApiInfo apiInfo() {
  32. Contact contact = new Contact("一个项目", "xxx", "xxx@126.com");
  33. return new ApiInfo(
  34. "交易所", // 标题
  35. "各种币的交易", // 描述
  36. "v1.0", // 版本
  37. "", // 组织链接
  38. contact, // 联系人信息
  39. "xx 2.0 许可", // 许可
  40. "xx", // 许可连接
  41. new ArrayList<>()// 扩展
  42. );
  43. }
  44. }

常用注解说明

@Api:用在类上,说明类的作用

  1. tags:“标签,可以在UI界面上看到的注解”
  2. valueurl的路径值,在类上使用的路由,如果类上没有配置,此注解无效
  3. position:如果配置多个Api 想改变显示的顺序位置
  4. protocols:协议
  5. hidden:配置为true 将在文档中隐藏
  6. produces:返回的文件的MIME类型,例如application/json,application/xml
  7. consumes:需要的文件的MIME类型,
  8. authorizations:认证

@ApiSort:排序

  1. valueint

@ApiOperation:用在方法上,用来给API增加方法说明。

  1. value=“说明方法的用途、作用”
  2. notes=“方法的备注说明”
  3. tags:如果设置这个值、value的值会被覆盖
  4. description:对api资源的描述
  5. basePath
  6. position
  7. protocols
  8. hidden
  9. response:返回的对象,例如(Bean.class
  10. responseContainer:返回的内容,有效的 List”, Set or Map”.,其他无效
  11. httpMethod
  12. code :默认为200
  13. extensions:扩展属性
  14. produces:返回的文件的MIME类型,例如application/json,application/xml
  15. consumes:需要的文件的MIME类型,
  16. ignoreJsonView:忽略的json

@ApiImplicitParam:用来注解来给方法入参增加说明。

  1. paramType:参数存在的位置,该参数不能乱写,否者测试时会调用失败
  2. header:请求参数放置于Request Header,使用@RequestHeader获取
  3. query:请求参数放置于请求地址,使用@RequestParam获取
  4. path:(用于restful接口)–>请求参数的获取:@PathVariable
  5. body@RequestBody
  6. form:表单提交
  7. name:参数名
  8. dataType:参数类型
  9. required:参数是否必须传(bool类型)
  10. value:说明参数的意思
  11. defaultValue:参数的默认值
  12. allowableValues:允许的值
  13. allowMultiple:是否允许多选
  14. allowEmptyValue:允许为空?
  15. readOnly:只读?

@ApiImplicitParams : 用在方法上包含一组参数说明。

  1. ApiImplicitParam[] value():包含ApiImplicitParam

@ApiResponses:用于表示一组响应

@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息

  1. code:数字,例如400
  2. message:信息,例如"请求参数没填好"
  3. response:响应类

@ResponseHeader:响应头设置

  1. name:响应名称
  2. description:描述信息
  3. response:响应类
  4. responseContainer:响应内容

@ApiModel:一般用在实体类,描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候

  1. @ApiModelProperty:描述一个model的属性
  2. 示例:
  3. @ApiModel(value = "日志")
  4. public class AccessLogBean implements Serializable {
  5. /**
  6. * 编号
  7. */
  8. @ApiModelProperty("编号")
  9. @Setter
  10. @Getter
  11. private int id;
  12. /**
  13. * 响应码
  14. */
  15. @ApiModelProperty("响应码")
  16. @Setter
  17. @Getter
  18. private String code = "";
  19. /**
  20. * 请求主机地址
  21. */
  22. @ApiModelProperty("请求主机地址")
  23. @Setter
  24. @Getter
  25. private String ip = "";

@ApiParam:使用在参数上(和ApiImplicitParam使用其一即可)
参数 意义

  • name 属性名称
  • value 属性值
  • defaultValue 默认属性值
  • allowableValues 可以不配置
  • required 是否属性必填
  • access
  • allowMultiple 默认为false
  • hidden 隐藏该属性
  • example

swagger配置文件详解

  1. swagger:
  2. production: false //如果此项设置为true,则swagger页面隐藏
  3. basic:
  4. enable: true //此项设置为true表示开启账号密码验证
  5. username: admin //enable为true时对应的登陆账号
  6. password: admin //enable为true时对应的登陆密码

关键字SpringBoot