zoukankan      html  css  js  c++  java
  • SpringBoot整合Swagger

    @Author:SimpleWu

    什么是Swagger?

    Swagger是什么:THE WORLD’S MOST POPULAR API TOOLING
    根据官网的介绍:
    Swagger Inspector:测试API和生成OpenAPI的开发工具。Swagger Inspector的建立是为了解决开发者的三个主要目标。

    • 执行简单的API测试
    • 生成OpenAPI文档
    • 探索新的API功能

    我的理解Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。简单来说,Swagger是一个功能强大的接口管理工具,并且提供了多种编程语言的前后端分离解决方案。根据我的使用,当然我只是最简单的使用,我感觉Swagger有以下几个优点:

    Swagger可以整合到代码中,在开发时通过注解,编写注释,自动生成API文档。
    将前端后台分开,不会有过分的依赖。

    界面清晰,无论是editor的实时展示还是ui的展示都十分人性化,如果自己仅仅用markdown来编写,又要纠结该如何展现,十分痛苦。

    构建项目

    step1.导入依赖
    	<!--swagger服务api构建个性包-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
    	<!--swagger ui界面-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
    	<!--springboot web服务-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    	<!--springboot单元测试-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    
    step2.编写swagger配置类

    想要使用swagger功能必须提供配置类,主要配置ui界面信息,以及配置扫描位置,swagger会根据配置的路径扫描所有的服务生成api。

    其中核心RequestHandlerSelectors.basePackage("com.simple.spring.boot.controller"),在这里配置我们的需要的扫描包位置。

    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.simple.spring.boot.controller"))
                .paths(PathSelectors.any()).build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("Spring Boot中使用Swagger2构建RESTful APIs")
            .description("myapp")
            .termsOfServiceUrl("http://blog.csdn.net/SimpleWu")
            .version("1.0").build();
        }
    }
    
    step3.编写springboot启动类

    @ComponentScan(basePackages={"com.simple.spring.boot.controller"}) 也是需要配置扫描路径。

    @SpringBootApplication
    @ComponentScan(basePackages={"com.simple.spring.boot.controller"})  
    public class SwaggerApplication {
        public static void main(String[] args) {
            SpringApplication.run(SwaggerApplication.class, args);
        }
    }
    
    step4.创建前端控制器
    @RestController
    @Api(tags = "swgger测试服务", description = "swgger测试服务")
    @RequestMapping(value = "/simple/wu")
    public class TestController {
    
        @ApiOperation(value="测试POST方法", notes="测试POST方法")
        @ApiImplicitParam(name = "令牌", value = "ID", required = true, dataType = "token")
        @RequestMapping(value="hello", method=RequestMethod.POST)
        public String post(@RequestBody String token) {
            books.put(book.getId(), book);
            return "success";
        }
    }
    
    1. @Api(tags = "swgger测试服务", description = "swgger测试服务") 指定某个类提供服务的名字
    2. @ApiOperation(value="测试POST方法", notes="测试POST方法") 指定某个请求的名字
    3. @ApiImplicitParam(name = "令牌", value = "token", required = true, dataType = "String")指定名字对应参数为令牌,以及对应参数字段token,required = true代表这个参数为必填参数,dataType 代表数据类型。
    step5.启动服务

    从上面的代码中我们指定请求为POST在UI界面上我们会看到一个服务名字为swgger测试服务的大类点击进去后可以看到里面所拥有的请求,如果指定这个请求的类型那么无法进行单元测试,指定后我们会看到一个请求名字叫做测试POST方法的请求并且需要填入必填参数token来完成我们的单元测试。

    我们可以直接通过SwaggerApplication类来运行main方法来进行服务,端口号默认为8080.

    swagger地址:http://localhost:8080/swagger-ui.html 只需要在地址后面加上swagger-ui.html即可访问

    我们访问这个位置即可看到UI界面,界面简洁并且容易上手,我这边就不截图了。

    step.总结

    swagger官方文档:https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api

    swagger的一个最大的优点是能实时同步api与文档。

    在项目开发过程中,发生过多次:修改代码但是没有更新文档,前端还是按照老旧的文档进行开发,在联调过程中才发现问题的情况(当然依据开闭原则,对接口的修改是不允许的,但是在项目不稳定阶段,这种情况很难避免)。

  • 相关阅读:
    jQuery插件开发模式
    优化布局
    jquery easyui 选项卡
    easy ui 点击行展开与折叠
    考拉海购技术支持的前世今生
    跑的好好的 Java 进程,怎么突然就瘫痪了
    Dubbo 如何成为连接异构微服务体系的最佳服务开发框架
    微服务治理实践:如何对单点异常进行自动摘除
    盘点阿里巴巴 15 款开发者工具
    千万创业者的自白:踩过坑才明白这些真相!
  • 原文地址:https://www.cnblogs.com/SimpleWu/p/10261140.html
Copyright © 2011-2022 走看看