springboot整合swagger3初体验

概述

日常的项目开发中无论是前端还是后端都会跟接口文档打交道,每一个开发者都期望有一个好的接口文档,但是实际开发过程中大家没少被接口文档折磨,前端抱怨后端给的接口文档不符合实际情况,后端觉得接口文档的编写和维护太麻烦,会浪费很多精力,故而不能做到实时的更新文档.为了解决这个痛苦于是有了swagger.swagger是一套对接口定义的规范,开发者只有按照其规范定义接口和接口相关信息, 然后通过Swagger自带的一些工具,就可以生成不同格式的接口文档

Swagger简介

官网

1.swagger提供的几种开源工具

Swagger Codegen:通过扫描生成的json文件,生成接口调用代码
Swagger UI:一个可视化的UI页面展示
Swagger Editor:Swagger描述文件的编辑器,支持实时预览描述文件的更新效果
Swagger Inspector:类型postman的作用,可以进行接口测试
Swagger Hub:类似github,可将描述文件上传到swagger hub上面

springboot + swagger3

1.pom依赖

直接使用springfox

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

2.创建配置类

package com.hz.controll.config;import io.swagger.annotations.ApiOperation;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;@EnableOpenApi
@Configuration
public class Swagger3Config {@Beanpublic Docket createRestApi(){Docket docket = new Docket(DocumentationType.OAS_30).apiInfo(apiInfo()).select()//设置通过什么方式定位需要自动生产文档的接口,这里定位方法上的注解@ApiOperation注解//,RequestHandlerSelectors.basePackage()通过扫描包.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//接口URI路径设置,any是全路径,也可以通过pathSelectors.regex()正则匹配.paths(PathSelectors.any()).build();return docket;}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("Swagger3接口文档").description("更多请咨询服务开发者子砚").contact(new Contact("子砚","https://www.baidu.com","13928121916@163.com")).version("1.2").build();}
}

3.controller

package com.hz.controll;import com.hz.dal.model.Clazz;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
@RequestMapping("/clazz")
@Api(tags = "班级信息管理")
public class ClazzController {@ApiOperation(httpMethod = "GET",value = "根据班级编号查询班级信息")@ApiImplicitParams({@ApiImplicitParam(name = "id",value = "班级编号",required = true,paramType = "path",dataType = "Long")})@GetMapping(value = "/clazzs/getClazzById/{id}")public Clazz getClazzById(@PathVariable(value = "id",required = true)Long id){Clazz clazz = new Clazz();clazz.setId(1L);clazz.setName("高三(1)班");return clazz;}}

4.相关注解说明

@Api:用在请求的类上，表示对类的说明tags="说明该类的作用，可以在UI界面上看到的注解"value="该参数没什么意义。在I界面上也看到，所以不需要配置"@Apioperation:用在请求的方法上，说明方法的用途、作用value="说明方法的用途、作用" notes="方法的备注说明"@ApiImplicitParams:用在请求的方法上，表示一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中，指定一个请求参数的各个方面name:参数名value:参数的汉字说明、解释required:参数是否必须传     paramType:参数放在哪个地方·header>请求参数的获取:@RequestHeader.query>请求参数的获取:@RequestParam.path(用于restful接口)>请求参数的获取:@PathVariable.div(不常用)    .form(不常用)
dataType:参数类型，默认string，其它值dataType="Integer" defaultValue:参数的默认值
@ApiResponses:用在请求的方法上，表示一组响应@ApiResponse:用在@ApiResponses中，一般用 于表达一个错误的响应信息 code:数字，例如400message:信息，例如"请求参数没填好" response:抛出异常的类
@ApiModel:用于响应类上，表示一个返回响应数据的信(这种一般用在post创建的时候，使用@ RequestBody这样的场景,请求参数无法使用@ApiImplicitParam往解进行描述的时候)@ApiModelProperty:用在属性上，描述响应类的属性

项目编写完成后本地启动项目,浏览器访问:
http://127.0.0.1:8080/swagger-ui/index.html

在这里插入图片描述
测试项目gitee地址