写点什么

在线问题反馈模块实战 (七): 安装部署 swagger2

作者:bug菌
  • 2022-10-21
    江苏
  • 本文字数:5126 字

    阅读完需:约 1 分钟

在线问题反馈模块实战(七):安装部署swagger2

👨‍🎓作者:bug 菌

✏️博客:​​CSDN​​​、​​掘金​​等

💌公众号:​​猿圈奇妙屋​

🚫特别声明:原创不易,转载请附上原文出处链接和本文声明,谢谢配合。

🙏版权声明:文章里可能部分文字或者图片来源于互联网或者百度百科,如有侵权请联系 bug 菌处理。 

一、前言🔥

       接下来的这几期,bug 菌想跟大家分享一下自己昨天刚接到一个临时的需求,热乎着呢,想分享一下自己是如何面对临时需求并制定整个开发周期,其中包括从梳理业务到创建业务表再到实现业务逻辑形成闭环再到与前端对接,其中会穿插一些业务拓展及功能性拓展,这一条龙流程在线与大家一起见证,分享给刚入门的小伙伴,希望对你们有所帮助。

环境说明:idea2019.3 + springboot2.3.1.REALSE + mybati-plus3.2.0 + mysql5.6 + jdk1.8

       若小伙伴们在批阅文章的过程中觉得文章对您有一丝丝帮助,还请别吝啬您手里的赞呀,大胆的把文章点亮👍吧,您的点赞三连(收藏⭐️+关注👨‍🎓+留言📃)就是对 bug 菌我创作道路上最好的鼓励与支持😘。时光不弃🏃🏻‍♀️,创作不停💕,加油☘️ 

二、正文🔥

        至于在上一期,有几个小伙伴私我,说 bug 菌,我们项目都还没有过这种在线接口文档,都还是采用那种还是手动实现的接口列表,我猜想,也正常,像我当初项目组,其实也不会用到这种通过内嵌到项目中的在线接口文档,但是你若没使用过它,你可能无法感知,一旦你用上了,你会知道,它不仅能解放你的双手,而且还支持接口一键导出,比如之前用到的手创的那个在线平台来着,一时间我都没想起来,然后也支持 swagger 脚本导入,然后接口及文档说明直接同步了过去。我才知道,那是真的强。

       说白了,Swagger 可以将项目中所有接口(想要暴露出去的接口)展现在页面上,并且提供接口调用和测试等服务,非常的 nice。

       所以啊,我要推荐给刚入门的你们,希望你们能把它用起来,帮助你们更高效的开发。

三、swagger 安装教程🔥

        我使用的组合版本为:swagger2 + 第三方 ui + swagger api 注解依赖联合引入。

1️⃣引入依赖

        在你的项目 pom.xml 依赖配置文件中,加上如下依赖包。尽量都复制完整,因为这是我实测过后的兼容稳定组合版本,你们直接拿去用就行,要非得搞点新花样,也不反对,但是用不了这个就别届时评论区抱怨哈。

<!--swagger2-->        <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger2</artifactId>            <version>2.7.0</version>            <!--排除传递性依赖(默认依赖指定版本的models跟annotations),避免报错-->            <exclusions>                <exclusion>                    <groupId>io.swagger</groupId>                    <artifactId>swagger-annotations</artifactId>                </exclusion>                <exclusion>                    <groupId>io.swagger</groupId>                    <artifactId>swagger-models</artifactId>                </exclusion>            </exclusions>        </dependency>
<!--Swagger第三方ui--> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.2</version> </dependency>
<!--提供Swagger api注解--> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-annotations</artifactId> <version>1.5.21</version> </dependency>
<!--swagger--> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> <version>1.5.21</version> </dependency>
复制代码

2️⃣配置 swagger 配置项

        如上依赖等下载完成后,接着就是要加上如下 swagger 配置了。其中对于.apis(),改成你项目的 Controller 包路径,接着 termsOfServiceUrl()配置项目启动地址,指定服务条款 url。


package com.example.review.config;
import com.example.review.util.ConstantUtils;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.ParameterBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.schema.ModelRef;import springfox.documentation.service.ApiInfo;import springfox.documentation.service.Contact;import springfox.documentation.service.Parameter;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;import java.util.List;

/** * swagger配置 * * @Author * @Date@Configuration //必须存在@EnableSwagger2 //必须存在public class SwaggerConfig {
/** * swagger文档配置 */ @Bean public Docket customDocket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.example.review.controller")) .paths(PathSelectors.any()) .build();// .globalOperationParameters(this.getParameterList());// 全局配置 }
/** * api相关配置 */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("swagger 接口文档") .contact(new Contact("review", "", "")) .description("swagger-bootstrap-ui") .termsOfServiceUrl("http://localhost:8888/") .version("1.0") .build(); }
}
复制代码


其中参数拓展:

  • swagger.title:标题

  • swagger.description:描述

  • swagger.version:版本

  • swagger.termsOfServiceUrl:服务条款 URL

  • swagger.contact.name:维护人

  • swagger.contact.url:维护人 URL

  • swagger.contact.email:维护人 email

3️⃣api 使用

​http://localhost:8889/review/doc.html​​;然后页面肯定啥也没有,是个空页面。

format,png

        接着我就给大家演示一下,给一个 Controller 和接口添加一些 api 注解,看看页面是有如何变化,比如我找到了 UserQuestionsController,给它加上如下注解:

@Api(tags = "问题反馈模块", description = "问题反馈模块")public class UserQuestionsController
复制代码

         接着是给其中的一个接口加上如下注解:

@ApiOperation(value = "反馈问题保存", notes = "反馈问题保存")    public ResultResponse<Boolean> saveQuestion(@ApiParam("图片数组") MultipartFile[] images,                                                @ApiParam("问题反馈类型") String questionType,                                                @ApiParam("问题反馈/建议描述") String questionContent,                                                @ApiParam("问题反馈/建议所在页面") throws IOException {        return
复制代码

你们可以试想一下,页面会有哪些内容变化?

4️⃣实例演示

         我就不卖关子啦,容我重启下项目,给大家展示一下:

        我直接打开左边的对应的[反馈问题保存],请你们再看一张图。

熟悉么?这不就是你们要手动创建的接口文档么,其中包含接口路径,接口请求方式、接口请求参数等,都自动帮你创建生成了,并且具体参数类型,是否必填,及参数说明都有自动生成。而且,你还可以进行接口调用测试,点击左上角的测试,你可以看到,界面神似 postman,都不需要你添加请求参数,你直接给定参数值即可,非常的好用。

接着附上一张我完整项目的 swagger 在线接口展示图,请看如下:

5️⃣api 拓展 

         对于 Controller 层、Entity 层,你们就可以用这些 swagger api。比如:@Api、@ApiOperation、@ApiModelProperty、@ApiModel 等。

比如对于 Controller 层,我们应该要有如下注解修饰:

/** * 问题反馈控制器 * * @author luoyong * @since@RestController@RequestMapping("/user-questions")@Api(tags = "问题反馈模块", description = "问题反馈模块")public class UserQuestionsController {

////}
复制代码


  • @RestController

作用:@controller 与 @ResponseBody 的结合。返回对象,对象数据直接以 JSON 或 XML 形式,写入 HTTP 响应(Response)中,这种就是属于 RESTful Web 服务。

  • @RequestMapping

作用:用来处理请求地址映射的注解,可用于类或方法上。

  • @Api

作用:使用在类上,表明是 swagger 资源。在你的 swagger 接口文档上会有对应标题及描述展示。

         暂时就介绍上代码中所涉及的那些注解,日后遇到别的咱们再接着拓展讲解。

        还有其他的 api 使用,我就打算日后遇到再给大家普及了吧。等你们先把项目配置 swagger 能正常跑起来再说哦,好不好。

四、往期热文推荐🔥

        对于问题反馈模块实战开发,我完整的梳理了每一期的教学及链接地址,仅供参考:希望能对你们有所帮助。

        如上是整整二十期内容,每一期都是干货,对于一个模块的开发,如何一点一滴打造并测试部署上线,我再说一遍,这不是演习,是实战!是实战!是实战!

        若你们觉得只是需要了解其中某个知识点或者业务的话,也不反对,你就选择其中的几期进行学习就好,反正都已经完结啦;我只希望你们能有所收获,有所成长,也就不枉我苦心每天下班后给大家总结更新。

五、文末🔥

​《springboot零基础入门教学》​​,都是我一手打下的江山,持续更新中,希望能帮助到更多小伙伴们。

       我是 bug 菌,一名想走👣出大山改变命运的程序猿。接下来的路还很长,都等待着我们去突破、去挑战。来吧,小伙伴们,我们一起加油!未来皆可期,fighting!

        最后送大家两句我很喜欢的话,与诸君共勉!


☘️做你想做的人,没有时间限制,只要愿意,什么时候都可以 start。

🍀你能从现在开始改变,也可以一成不变,这件事,没有规矩可言,你可以活出最精彩的自己。




💌如果文章对您有所帮助,就请留下您的吧!(#^.^#);

💝如果喜欢 bug 菌分享的文章,就请给 bug 菌点个关注吧!(๑′ᴗ‵๑)づ╭❤~;

💗如果对文章有任何疑问,还请文末留言或者加群吧【QQ 交流群:708072830】;

💞鉴于个人经验有限,所有观点及技术研点,如有异议,请直接回复参与讨论(请勿发表攻击言论,谢谢);

💕版权声明:原创不易,转载请附上原文出处链接和本文声明,版权所有,盗版必究!!!谢谢。


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

bug菌

关注

公众号 | 猿圈奇妙屋 2020-07-30 加入

在CSDN、掘金等社区优质创作者,全网合计6w粉+,对一切技术都感兴趣,重心偏java方向,目前运营公众号[猿圈奇妙屋],欢迎小伙伴们的加入,一起秃头。

评论

发布
暂无评论
在线问题反馈模块实战(七):安装部署swagger2_springboot_bug菌_InfoQ写作社区