企业官网建设流程全解析

全网通官方网站,建设vip电影网站,ps做网站主页图片,兰州网站seo服务大家好#xff0c;我是小悟。 有没有遇到过这样的尴尬场景#xff1f; 前端小妹跑来问你#xff1a;“哥哥#xff0c;这个用户列表接口怎么调用呀#xff1f;” 你自信满满#xff1a;“看文档啊#xff01;” 然后她发来一张截图——你去年写的Word文档#xff0c;上…大家好我是小悟。有没有遇到过这样的尴尬场景前端小妹跑来问你“哥哥这个用户列表接口怎么调用呀”你自信满满“看文档啊”然后她发来一张截图——你去年写的Word文档上面写着GET /api/users 大概是这个吧我也忘了 可能需要token不确定 参数...自己猜吧这时候你就需要Swagger——它就像是给你的API开了个24小时真人直播秀让前端、测试、甚至产品经理都能直接看到每个接口的“素颜”状态什么是Swagger想象一下你的API是个害羞的宅男从来不出门见人。Swagger就是那个逼他穿上西装自动生成文档站在聚光灯下可视化界面还自带使用说明书在线测试最妙的是这哥们还会自动更新代码一改文档立刻变再也不用担心“文档版本落后于代码”这种史诗级bug了。开始整活SpringBoot集成Swagger详细步骤第1步添加依赖——给项目“注射美容针”!-- pom.xml 里加入这些“营养品” -- dependency groupIdio.springfox/groupId artifactIdspringfox-boot-starter/artifactId version3.0.0/version /dependency !-- 如果你用的是Swagger3推荐 -- dependency groupIdio.springfox/groupId artifactIdspringfox-boot-starter/artifactId version3.0.0/version /dependency或者用Gradle的小伙伴// 在build.gradle里“加点料” implementation io.springfox:springfox-boot-starter:3.0.0第2步创建配置类——给Swagger“办个身份证”package com.example.demo.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; Configuration public class SwaggerConfig { Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) .select() // 扫描的包路径就像告诉Swagger“去这个包厢找人” .apis(RequestHandlerSelectors.basePackage(com.example.demo.controller)) // 扫描所有路径相当于“这个KTV所有房间都看看” .paths(PathSelectors.any()) .build() .enable(true) // 想关闭Swagger时改成false就像“今天不营业” .groupName(默认分组); // 可以分多个组就像给API分班级 } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title(API文档标题) .description( 这里是详细的描述可以写很长很长... 比如 1. 这个系统是干什么的 2. 接口有什么特殊要求 3. 常见的错误码说明 支持Markdown语法哦 ) .contact(new Contact( 你的名字, https://github.com/yourname, your.emailexample.com )) .version(v1.0.0) .license(MIT License) .licenseUrl(https://opensource.org/licenses/MIT) .termsOfServiceUrl(http://localhost:8080) .build(); } }第3步Controller添加注解——给API“化妆打扮”package com.example.demo.controller; import io.swagger.annotations.*; import org.springframework.web.bind.annotation.*; RestController RequestMapping(/api/users) Api(tags 用户管理模块, value 用户相关的所有操作) public class UserController { GetMapping(/{id}) ApiOperation(value 根据ID查询用户, notes 注意id必须是正整数) ApiImplicitParams({ ApiImplicitParam( name id, value 用户ID, required true, dataType Long, paramType path, example 123 ) }) ApiResponses({ ApiResponse(code 200, message 成功), ApiResponse(code 404, message 用户不存在), ApiResponse(code 500, message 服务器开小差了) }) public User getUser(PathVariable Long id) { // 你的业务逻辑 return userService.findById(id); } PostMapping(/) ApiOperation(value 创建用户, notes 创建一个新用户) public User createUser( ApiParam(value 用户对象, required true) RequestBody UserDTO userDTO) { return userService.create(userDTO); } // 实体类也要加注解这样Swagger才知道字段的含义 ApiModel(description 用户实体) public static class User { ApiModelProperty(value 用户ID, example 1) private Long id; ApiModelProperty(value 用户名, example 张三, required true) private String username; ApiModelProperty(value 邮箱, example zhangsanexample.com) private String email; // getters and setters } }第4步配置文件调整——解决“404尴尬症”# application.yml spring: mvc: pathmatch: matching-strategy: ant_path_matcher # 解决SpringBoot2.6的兼容问题 # 如果想自定义Swagger路径 springfox: documentation: swagger-ui: path: /swagger-ui.html # 默认就是这个 enabled: true第5步启动并访问——见证奇迹的时刻启动SpringBoot应用打开浏览器访问http://localhost:8080/swagger-ui/或者访问http://localhost:8080/swagger-ui/index.html你会看到一个漂亮的界面左边是API列表右边是详细说明还可以直接点击“Try it out”测试接口高级玩法——给Swagger“加特效”1. 分组显示适合微服务Bean public Docket userApi() { return new Docket(DocumentationType.OAS_30) .groupName(用户模块) .select() .apis(RequestHandlerSelectors.basePackage(com.example.user)) .build(); } Bean public Docket orderApi() { return new Docket(DocumentationType.OAS_30) .groupName(订单模块) .select() .apis(RequestHandlerSelectors.basePackage(com.example.order)) .build(); }2. 添加全局tokenBean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) .securitySchemes(Collections.singletonList( new ApiKey(Authorization, Authorization, header) )) // ...其他配置 }3. 自定义响应消息Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) .globalResponses(HttpMethod.GET, Arrays.asList( new ResponseBuilder() .code(500) .description(服务器内部错误) .build(), new ResponseBuilder() .code(403) .description(没有权限) .build() )) // ...其他配置 }常见问题及解决方案问题1访问/swagger-ui/报404解决方案 1. 检查依赖是否正确 2. 添加EnableOpenApi注解Swagger3 3. 检查SpringBoot版本兼容性问题2界面出来了但没显示API解决方案 1. 检查RestController是否在扫描包内 2. 检查RequestMapping等注解是否正确 3. 检查Docket配置的路径选择器问题3生产环境想关闭Swagger# application-prod.yml springfox: documentation: enabled: false或者用Profile控制Profile({dev, test}) // 只在开发测试环境生效 Configuration public class SwaggerConfig { // 配置内容 }总结Swagger到底香不香优点为什么你要用自动生成文档代码即文档改了代码文档自动更新告别“文档滞后”在线测试前端不用等你了自己就能测试接口协作神器前后端对接再也不用“传纸条”支持多种格式可以导出JSON、YAML等格式社区活跃遇到问题容易找到解决方案缺点你要注意的代码侵入性注解会让Controller看起来有点“胖”性能影响生产环境建议关闭学习成本各种注解需要时间熟悉最后小项目用Swagger就像给自行车装导航——方便大项目用Swagger就像给航母装GPS——必须不用Swagger就像开车不看路标——容易撞墙好的API文档不是写出来的是“生成”出来的。Swagger就是你的API的专属化妆师摄影师经纪人让你的接口从“代码宅男”变身“流量明星”现在给你的SpringBoot项目装上Swagger吧让前端妹子对你刮目相看谢谢你看我的文章既然看到这里了如果觉得不错随手点个赞、转发、在看三连吧感谢感谢。那我们下次再见。您的一键三连是我更新的最大动力谢谢山水有相逢来日皆可期谢谢阅读我们再会我手中的金箍棒上能通天下能探海