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

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

springboot集成Swagger2 3.0以下版本

io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.2

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版本使用更加简单

io.springfox springfox-boot-starter 3.0.0

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 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这个注解

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(tags = "入门小站Controller入口",value = "页面上看不见的内容")

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

入参数说明

@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({@ApiResponse(code = 200,message = "成功"),@ApiResponse(code=201,message = "参数错误")})

描述实体类

@ApiModel("用戶信息")

描述实体类的属性

@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开发手册

Spring Boot

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。