文章详情

短信预约-IT技能 免费直播动态提醒

请输入下面的图形验证码

提交验证

短信预约提醒成功

JavaSwagger使用教程

2024-04-02 19:55

关注

Swagger简介

为什么使用Swagger

  这个问题就牵涉到技术的更新迭代了,在之前的后端时代,前端只需要管理静态页面,而后端需要使用模板引擎(JSP等)去得数据并加以处理,最后显示出数据。但是随着时代的发展,开发慢慢进入了前后端分离的时代,前端和后端分成了两个相对独立的团队来合作开发,这就造成了一个问题:前后端集成联调的时候,前后端人员无法做到“及时协商,尽早解决”,最终造成问题的集中爆发。

  既然已经发现问题,那么就需要使用一种解决方案来避免这个问题的干扰。做过一个完整项目的小伙伴应该都有所了解,前后端之间的协作基本上都在api接口和数据传输上,那么如果api接口能够统一、数据的格式能够一致,那么问题也就迎刃而解了。

  于是Swagger应运而生,Swagger可以根据在代码中使用自定义的注解来生成接口文档,这样做的好处是在开发接口时可以通过swagger将接口文档定义好,方便前后端团队之间的协作,同时也方便以后的维护。

Swagger的配置

Spring boot集成Swagger

新建一个spring boot项目

导入两个依赖

<!--Swagger(开始)-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!--Swagger(结束)-->

配置Swagger

@Configuration
@EnableSwagger2     // 开启Swagger2
public class SwaggerConfig {
}

  如果只是使用配置类开启Swagger的话,它的底层会有一些DEFAULT(默认)的值,开启之后就可以使用网址http://localhost:8080/swagger-ui.html来访问这个Swagger的文档界面。

  

当然,既然有默认的配置,我们就可以实现定制化的配置覆盖,依然是在这个配置类中进行修改

@Configuration
@EnableSwagger2     // 开启Swagger2
public class SwaggerConfig {
    
    @Bean
    public Docket Docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(ApiInfo());
    }
    
    private ApiInfo ApiInfo() {
        // 作者的个人信息
        Contact contact = new Contact("作者的姓名", "作者的个人社交主页", "作者的邮箱");
        return new ApiInfo(
                "Swagger的测试接口文档",
                "简介:这是一段简介,关于接口文档的简介",
                "版本号:1.0",
                "网页:这是一个网页链接",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()
        );
    }
}

  修改之后的页面信息就会有一些不一样,restart项目之后重新访问ui界面

配置Swagger可扫描的接口

  这一部分的工作也是在SwaggerConfig配置类中实现,主要就是配置哪些api接口会被Swagger生成接口文档,生成文档的api就会在swagger的ui界面上显示。通过以下.apis和.paths的配置,达到的效果就是之后在com.xiaochen.swagger.controller包下的且映射路径为/hello的才会生成对应的接口文档

 @Bean
public Docket Docket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            
            .apis(RequestHandlerSelectors.basePackage("com.xiaochen.swagger.controller"))
            
            .paths(PathSelectors.ant("/hello"))
            .build()
            .apiInfo(ApiInfo());
}

控制Swagger的开关

  使用.enable可以控制Swagger的开关,如果关闭了Swagger的话就会导致ui界面无法打开,也就无法查看接口文档

  

那么该如何实现只在开发和测试阶段开启Swagger呢?首先应该先预设一下想要开启的项目环境,通过Environment 对象来监听项目的环境与预设的是否一致,最后使用.enable控制Swagger的开关

@Bean
public Docket Docket(Environment environment) {
    // 预设的项目环境(可设置多个)
    Profiles profiles = Profiles.of("dev", "test");
    // 监听项目的环境与预设的是否一致
    boolean flag = environment.acceptsProfiles(profiles);
    return new Docket(DocumentationType.SWAGGER_2)
            .enable(flag);
}

设置Swagger的分组

  在没有设置Swagger的分组之前,有一个默认的default分组,分组个数的多少就取决于SwaggerConfig 配置类中有多少个Docket 实例,值得注意的是:不能出现同名的分组,即使是未命名的分组(也就是default)也不能重复出现,否则就会报java.lang.IllegalStateException异常

Swagger的各种注释

controller层使用到的注解

entity层使用到的注解

  model里面是否有这个实体类,并不是取决于是否使用了哪个注解,而是方法的返回值是否包含这个实体类对象,也就是看有没有一个方法return了这个对象。

使用Swagger接口测试

这里的使用和postman几乎一样,可以借鉴学习

到此这篇关于Java Swagger使用教程的文章就介绍到这了,更多相关Java Swagger内容请搜索编程网以前的文章或继续浏览下面的相关文章希望大家以后多多支持编程网!

阅读原文内容投诉

免责声明:

① 本站未注明“稿件来源”的信息均来自网络整理。其文字、图片和音视频稿件的所属权归原作者所有。本站收集整理出于非商业性的教育和科研之目的,并不意味着本站赞同其观点或证实其内容的真实性。仅作为临时的测试数据,供内部测试之用。本站并未授权任何人以任何方式主动获取本站任何信息。

② 本站未注明“稿件来源”的临时测试数据将在测试完成后最终做删除处理。有问题或投稿请发送至: 邮箱/279061341@qq.com QQ/279061341

软考中级精品资料免费领

  • 历年真题答案解析
  • 备考技巧名师总结
  • 高频考点精准押题
  • 2024年上半年信息系统项目管理师第二批次真题及答案解析(完整版)

    难度     813人已做
    查看
  • 【考后总结】2024年5月26日信息系统项目管理师第2批次考情分析

    难度     354人已做
    查看
  • 【考后总结】2024年5月25日信息系统项目管理师第1批次考情分析

    难度     318人已做
    查看
  • 2024年上半年软考高项第一、二批次真题考点汇总(完整版)

    难度     435人已做
    查看
  • 2024年上半年系统架构设计师考试综合知识真题

    难度     224人已做
    查看

相关文章

发现更多好内容

猜你喜欢

AI推送时光机
位置:首页-资讯-后端开发
咦!没有更多了?去看看其它编程学习网 内容吧
首页课程
资料下载
问答资讯