写点什么

第九节:SpringBoot 在线文档 Swagger2 入门

作者:入门小站
  • 2022 年 2 月 10 日
  • 本文字数:3898 字

    阅读完需:约 13 分钟

Swagger2 是一个开源项目,用于为 RESTful Web 服务生成 REST API 文档。它提供了一个用户界面,可以通过 Web 浏览器访问我们的 RESTful Web 服务,测试接口。

SpringBoot 集成 Swagger2 3.0 以下版本

pom.xml

<dependency>  <groupId>io.springfox</groupId>  <artifactId>springfox-swagger2</artifactId>  <version>2.9.2</version></dependency><dependency>  <groupId>io.springfox</groupId>  <artifactId>springfox-swagger-ui</artifactId>  <version>2.9.2</version></dependency>
复制代码

Swagger2Config配置文件

package com.rumenz.lession9.controller.config;
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;import springfox.documentation.swagger2.annotations.EnableSwagger2;
/** * @className: Swagger2Config * @description: TODO 类描述 * @author: 入门小站 rumenz.com * @date: 2021/11/10 **/
@Configuration@EnableSwagger2 //Swagger2 3.0以下版本需要开启的注解public class Swagger2Config {
@Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.rumenz.lession9.controller")) .paths(PathSelectors.any()).build(); } private ApiInfo apiInfo(){ Contact contact=new Contact("入门小站", "https://rumenz.com", "xenry@163.com"); return new ApiInfoBuilder() .title("入门小站接口文档") .description("https://rumenz.com") .contact(contact).build(); }}
复制代码


3.0 以下开启@EnableSwagger2这个注解


浏览器访问http://127.0.0.1:8080/swagger-ui.html


SpringBoot 集成 Swagger2 3.0 以版本

Swagger2 3.0 版本使用更加简单

pom.xml

<dependency>  <groupId>io.springfox</groupId>  <artifactId>springfox-boot-starter</artifactId>  <version>3.0.0</version></dependency>
复制代码

Swagger2Config配置问价相差不大。

package com.rumenz.lession9.controller.config;
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;import springfox.documentation.swagger2.annotations.EnableSwagger2;
/** * @className: Swagger2Config * @description: TODO 类描述 * @author: 入门小站 rumenz.com * @date: 2021/11/10 **/
@Configurationpublic class Swagger2Config {
@Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.rumenz.lession9.controller")) .paths(PathSelectors.any()).build(); } private ApiInfo apiInfo(){ Contact contact=new Contact("入门小站", "https://rumenz.com", "xenry@163.com"); return new ApiInfoBuilder() .title("入门小站接口文档") .description("https://rumenz.com") .contact(contact).build(); }}
复制代码


3.0 以上版本不需要@EnableSwagger2这个注解

启动类添加注解

package com.rumenz;
import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;import springfox.documentation.oas.annotations.EnableOpenApi;
@SpringBootApplication@EnableOpenApi //Swagger2 3.0以上版本需要开启的注解public class Lession9Application {
public static void main(String[] args) { SpringApplication.run(Lession9Application.class, args); }
}
复制代码


注意添加@EnableOpenApi注解


浏览器访问http://127.0.0.1:8080/swagger-ui/


Swagger2 常用注解

@Api

@Api 用在类上,用于说明类功能的说明


@Api(tags = "入门小站Controller入口",value = "页面上看不见的内容")
复制代码


@ApiOperation

@ApiOperation(value = "方法的作用说明",notes = "方法的备注说明")
复制代码


@ApiImplicitParams,@ApiImplicitParam

入参数说明


@ApiImplicitParams({@ApiImplicitParam(name = "page",value = "当前页"),@ApiImplicitParam(name = "pageSize",value = "分页大小")})
复制代码


@ApiImplicitParam其它参数


@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面        name:参数名        value:参数的汉字说明、解释        required:参数是否必须传        paramType:参数放在哪个地方            · header --> 请求参数的获取:@RequestHeader            · query --> 请求参数的获取:@RequestParam            · path(用于restful接口)--> 请求参数的获取:@PathVariable            · body(不常用)            · form(不常用)            dataType:参数类型,默认String,其它值dataType="Integer"               defaultValue:参数的默认值
复制代码


@ApiResponses

明请求返回的状态码及描述


@ApiResponses({@ApiResponse(code = 200,message = "成功"),@ApiResponse(code=201,message = "参数错误")})
复制代码


@ApiModel

描述实体类


@ApiModel("用戶信息")
复制代码


@ApiModelProperty

描述实体类的属性


@ApiModelProperty(value = "名字",name = "name",example = "入门小站")
复制代码


演示案例

RumenzController


package com.rumenz.lession9.controller;
import io.swagger.annotations.*;import lombok.AllArgsConstructor;import lombok.Data;import lombok.NoArgsConstructor;import org.springframework.web.bind.annotation.*;
/** * @className: RumenzController * @description: TODO 类描述 * @author: 入门小站 rumenz.com * @date: 2021/11/10 **/@RestController@RequestMapping("/rumenz")//@Api用在类上,用于说明类功能的说明@Api(tags = "入门小站Controller入口",value = "页面上看不见的内容")public class RumenzController {
@GetMapping("/index") public String index(){ return "入门小站"; }
@GetMapping("/user") @ApiOperation(value = "方法的作用说明",notes = "方法的备注说明") //传入参数说明 @ApiImplicitParams({@ApiImplicitParam(name = "page",value = "当前页"),@ApiImplicitParam(name = "pageSize",value = "分页大小")}) //说明请求返回的状态码及描述 @ApiResponses({@ApiResponse(code = 200,message = "成功"),@ApiResponse(code=201,message = "参数错误")}) public String index1(@ApiParam("页数") @RequestParam("page") Integer page,@ApiParam("每页条数") Integer pageSize){ return "入门小站"; }
@PostMapping("/save") @ApiOperation("保存用户") public String save(@RequestBody User user){ return "入门小站"; }
}@Data@NoArgsConstructor@AllArgsConstructor//描述实体类@ApiModel("用戶信息")class User { //描述实体类的属性 @ApiModelProperty(value = "名字",name = "name",example = "入门小站") private String name;
@ApiModelProperty(value = "年龄",name="age",example = "20") private Integer age;
@ApiModelProperty(value = "地址",name="address",example = "rumenz.com") private String address;
@ApiModelProperty(value = "邮箱",name="email",example = "372669319@qq.com") private String email;
}
复制代码


在线测试接口可以点击Try it out填入相关参数测试。


本小结源码地址:


  • GitHub:https://github.com/mifunc/springboot/tree/main/lession8

  • Gitee:https://gitee.com/rumenz/springboot/tree/master/lession8

  • https://rumenz.com/rumenbiji/springboot-swagger20-rumen.html


介绍


  • 我的博客 https://rumenz.com/ ,

  • 我的工具箱 https://tooltt.com/

  • 微信公众号:【入门小站】



  • 关注【入门小站】回复【1001】获取 linux 常用命令速查手册

  • 关注【入门小站】回复【1003】获取 LeetCode 题解【java 语言实现】

  • 关注【入门小站】回复【1004】获取 Java 基础核心总结

  • 关注【入门小站】回复【1009】获取 阿里巴巴 Java 开发手册

发布于: 刚刚阅读数: 2
用户头像

入门小站

关注

还未添加个人签名 2020.01.18 加入

还未添加个人简介

评论

发布
暂无评论
第九节:SpringBoot在线文档Swagger2入门