目录前言：什么是Swagger启动：（简单3步）加载依赖添加注解@EnableOpenApi启动SpringBoot，访问Swagger后台接口配置：基于Java的配置注解：Swagger2和Swagger3供对比源码：https://github.com/Jalon2015/...问题：踩坑记录（稍后整理）前言什么是Swagger：Swagger是最流行的API开发工具，它紧跟OpenAPI规范（OpenAPISpecification，也简称为OAS）。它最方便的特点是API文档可以和服务器保持同步，即服务器更新一个接口，前端API文档可以更新实时并可在线测试。这样一来，Swagger大大降低了前后端之间的沟通壁垒，再也不用因为一个接口不能调整而争论不休了。之前使用的云文档，但是这种第三方的需要手动维护，启动加载依赖还是不方便io.springfoxspringfox-boot-starter3.0.0添加@EnableOpenApi注解@EnableOpenApi@SpringBootApplicationpublicclassSwaggerApplication{publicstaticvoidmain(String[]args){SpringApplication.run(SwaggerApplication.class,args);}}启动项目，访问一个简单的Swagger后台类似“http://localhost:8080/swagger-ui/index.html”的接口文件搭建；下面说说配置和注解配置。可以看到在上面的界面中，默认显示了一个basic-error-controller界面组，但是我们没有写；通过在项目中查找，我们发现，SpringBoot内部确实存在这样一个控制器类，如下图：这说明Swagger默认配置会自动在接口文档中添加@Controller控制器类。我们自己配置一下，如下图：importio.swagger。annotations.ApiOperation；导入io.swagger.v3.oas.annotations.Operation；导入io.swagger.v3.oas.annotations.tags.Tag；导入org.springframework.context.annotation.Bean；导入org.springframework.context。注解.配置持续时间；导入springfox.documentation.builders.ApiInfoBuilder；导入springfox.documentation.builders.PathSelectors；导入springfox.documentation.builders.RequestHandlerSelectors；导入服务springfox.documentation.oas.annotations.EnableOpenApi；importInfoimportspringfox.document；Apimentspringfox.documentation.service.Contact;importspringfox.documentation.spi.DocumentationType;importspringfox.documentation.spring.web.plugins.Docket;@ConfigurationpublicclassSwaggerConfig{@BeanpublicDocketcreateRestApi(){//配置OAS3.0协议returnnewDocket(DocumentationType.OAS_30).apiInfo(apiInfo()).select()//找到@Tag注解的类，生成对应的组；该类下的所有http请求方法都会生成相应的API接口//通过这个配置可以排除那些没有添加@Tag注解的controller类。apis(RequestHandlerSelectors.withClassAnnotation(Tag.class)).paths(PathSelectors.any()).build();}私有ApiInfoapiInfo(){returnnewApiInfoBuilder().title("GPSDoc").description("GPSDoc文档").termsOfServiceUrl("http://www.javalover.com").contact(newContact("javalover","http://www.javalover.cn","1121263265@qq.com")).version("2.0.0").build();}}上面的basic-error-controller会不可见注解我们先来看Swagger2中的注解，如下：@Api：用在controller类上，表示类标签的描述=“类的功能描述”,UI界面上可以看到的描述信息之一简单易用的注解"value="这个参数没有意义，在UI界面上也可以看到，所以不用配置"@ApiOperation:usedontherequestedmethod，说明方法的目的和作用value="describesthepurposeandfunctionofthemethod"notes="Remarksonthemethod"@ApiImplicitParams：在请求方法中使用，表示一组参数说明@ApiImplicitParam:用在@ApiImplicitParams注解中，用于指定一个请求参数的各个方面（标记一个指定的参数，并详细概括参数的各个方面，如：参数名称是什么？参数的含义，是否必填,等)name:属性值为方法参数名value:参数含义的汉字描述和解释required:参数是否必须传递paramType:参数放在哪里header-->请求参数的获取:@RequestHeaderquery-->请求参数的获取：@RequestParampath（针对restful接口）-->请求参数的获取：@PathVariabledataType：参数类型，默认String，其他取值dataType="Integer"defaultValue：默认值参数@ApiResponses：用在请求的方法中，表示一组响应应该是@ApiResponse：用在@ApiResponses中，一般用来表示一个错误的响应信息:用于响应类（POJO实体类）上，描述返回响应数据的信息（描述POJO类请求或响应的实体描述）（这个一般用在post接口中，使用@RequestBody在接收数据JSON格式，请求时参数无法使用@ApiImplicitParam注解描述）@ApiModelProperty：用在POJO属性上，用于描述响应类的属性描述@ApiIgnore：使用该注解忽略此某个API或参数；上面是Swagger2的注解，下面看Swagger3和它的简单对比接下来我们用Swagger3的注解写一个接口看看效果（中间穿插Swagger2的注解）controllerUserController.javaimportio.swagger.annotations.Api;importio.swagger.注释。ApiImplicitParam；导入io.swagger.annotations.ApiImplicitParams；导入io.swagger.annotations.ApiOperation；导入io.swagger.v3.oas.annotations.Hidden；导入io.swagger.v3.oas.annotations.Operation；导入io.swagger.v3.oas.annotations.Parameter；导入io.swagger.v3.oas.annotations.Parameters；导入io.swagger.v3.oas.annotations.enums.ParameterIn；导入io.swagger.v3.oas.annotations.tags。标记；导入org.springframework.web.bind.annotation.*；导入springfox.documentation.annotations.ApiIgnore;@Tag(name="user-controller",description="UserInterface")@RestControllerpublicclassUserController{//忽略这个api@Operation(hidden=true)@GetMapping("/hello")publicString你好（）{返回“你好”；}@Operation(summary="Userinterface-getuserdetails")@GetMapping("/user/detail")//这里的@Parameter也可以省略，Swagger会自动识别这个name参数//但是加上@Parameter注解可以添加一些有用的信息，例如descriptionuser.setUsername(名称);user.setPassword("123");返回用户；}@Operation(summary="UserInterface-AddUser")@PostMapping("/user/add")//这里的用户会被Swagger自动识别publicUseraddUser(@RequestBodyUseruser){System.out.println（“添加用户”）;返回用户；}}实体类User.java:importio.swagger.annotations.ApiModel;导入io.swagger.annotations.ApiModelProperty；导入io.swagger.v3.oas.annotations.media.S模式；导入lombok.Data；@Schema@DatapublicclassUser{@Schema(name="username",description="username",example="javalover")privateStringusername;@Schema(name="password",description="password",example="123456")privateStringpassword;//隐藏该属性，使接口文档的请求参数中看不到该属性@Schema(hidden=true)privateStringemail;}启动后运行界面如下：首页显示：/user/addinterfacedisplay:/user/detail界面显示源码整理在Github上：https://github.com/Jalon2015/...问题只是一个简单的经验，其实还是有很多坑的，而且以后有时间我会整理一下。这里有几个：@Paramters参数无效@ApiImplicitParamter的body属性无效@Tag的name属性：如果name属性不是当前类名的小写连字符格式，会被识别为一个单独的接口组等最近整理了一份采访资料《Java面试题-校招版》，有答案，无密码无水印，有兴趣的可以关注公众号，回复“采访”领取
