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

举报
bug菌 发表于 2023/05/11 23:26:18 2023/05/11
【摘要】 我是bug菌,一名想走👣出大山改变命运的程序猿。接下来的路还很长,都等待着我们去突破、去挑战。来吧,小伙伴们,我们一起加油!未来皆可期,fighting!


👨‍🎓作者:bug菌
✏️博客:CSDN掘金infoQ51CTO
🎉简介:CSDN/阿里云/华为云/51CTO 博客专家,博客之星Top30,掘金年度人气作者Top40,51CTO年度博主Top12,掘金/InfoQ/51CTO等社区优质创作者,全网粉丝合计10w+,硬核微信公众号猿圈奇妙屋」,欢迎你的加入!免费领取简历模板/学习资料/大厂面试真题/职业规划等海量资料。
..
✍️温馨提醒:本文字数:1999字, 阅读完需:约 6 分钟

        嗨,家人们,我是bug菌呀,我又来啦。今天我们来聊点什么咧,OK,接着为大家更《springboot零基础入门教学》系列文章吧。希望能帮助更多的初学者们快速入门!

        如果小伙伴们在批阅文章的过程中觉得文章对自己有帮助,请别吝啬手中的赞呀,大胆的把文章点亮👍,相信你点赞了好的文章,平台也会经常给你推荐高质量好文,您的点赞三连(收藏+关注+留言)就是对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 2021-06-01 13:00
 */
@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使用

        然后启动项目,直接访问:ip:port/doc.html.也就是你们的项目启动路径加“/doc.html”。比如我这: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("问题反馈/建议所在页面") String inPage) throws IOException {
        return userQuestionsService.saveQuestion(images, questionType, questionContent, inPage);
    }

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

4️⃣实例演示

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


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

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

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

5️⃣api拓展 

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

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


  •  @RestController

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

  •  @RequestMapping

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

  •  @Api

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

         暂时就介绍上代码中所涉及的那些注解,日后遇到别的咱们再接着拓展讲解。        还有其他的api使用,我就打算日后遇到再给大家普及了吧。等你们先把项目配置swagger能正常跑起来再说哦,好不好。

... ...

        好啦,以上就是这期的所有内容啦,你们学废了么?如果对你有所帮助,还请不要忘记给bug菌[三连支持]哟。如果想获得更多的学习资源或者想和更多的技术爱好者一起交流,可以关注我的公众号『猿圈奇妙屋』,后台回复关键词领取学习资料、大厂面经、面试模板等海量资源,就等你来拿。

三、往期热文推荐🔥

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

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

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

四、文末🔥

        如果还想要学习更多,小伙伴们直接订阅bug菌专门为大家创建的零基础入门Spring Boot专栏《滚雪球学Spring Boot》,从无到有,从零到一!以知识点+实例+项目的学习模式由浅入深对Spring Boot框架进行学习&使用。

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

我的博客即将同步至腾讯云开发者社区,邀请大家一同入驻:https://cloud.tencent.com/developer/support-plan?invite_code=273amm8tneckc

【版权声明】本文为华为云社区用户原创内容,转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息, 否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。