zoukankan      html  css  js  c++  java
  • 认识界上最流行的Api框架——swagger

    认识界上最流行的Api框架——swagger

    swagger简介

    swagger是支持多种编程语言的Api框架。可以直接运行,在线测试API接口。有RestFul Api文档在线自动生成工具,并且能够达到Api文档与API定义同步更新

    由于前端和后端分离式开发的广泛应用,许多前端人员无法做到问题处理同步,为了提高问题的处理效率,以及避免工作中前后端工作人员的矛盾,就需要‘即时协商,目标同步’。对于这个问题,最早的解决方法是使用:指定schema并实时更新最新API、word计划文档、后端提供接口,前端用postman测试后端接口三种方法。但是这几种方法并不能达到即时的效果,所以swagger就应时而生。

    作为世界上最流行的API框架,swagger在项目中使用时需要springfox(swagger2和swagger-ui)。这就需要在项目中导入以下两个依赖:

    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
    
    

    用SpringBoot集成swagger

    1. 新建SpringBoot web项目

    2. 导入swagger2和swagger-ui依赖

    3. 编写一个hello工程用于测试

    4. 配置swagger,编写config

      @Configuration
      @EnableSwagger2        //开启Swagger2
      public class SwaggerConfig {
      }
      
    5. 运行测试:http://localhost:8080/swagger-ui.html

    配置swagger信息

    1. swagger的bean实例docket:

      @Bean
      public Docket docket(){
          return new Docket(DocumentationType.SWAGGER_2);
      }
      
    2. 配置swagger的信息:

      //配置Swagger信息=apiInfo
      private ApiInfo apiInfo(){
          //作者信息
          Contact contact = new Contact("啊侠", "https://blog.csdn.net/weixin_44821160", "792228573@qq.com");
          return new ApiInfo(
              "啊侠的SwaggerAPI测试文档",
              "不要因为任何事情忘记自己最初的动力",
              "v1.0",
              "https://blog.csdn.net/weixin_44821160",
              contact,
              "Apache 2.0",
              "http://www.apache.org/licenses/LICENSE-2.0",
              new ArrayList()
          );
      }
      

    swagger配置扫描接口

    Docket.select()

    //配置了Swagger的Docket的bean实例
        @Bean
        public Docket docket(){
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    //RequestHandlerSelectors,配置要扫描接口的方式
                    //basePackage:指定要扫描的包
                    //any():扫描全部
                    //none():不扫描
                    //withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象
                    //withMethodAnnotation:扫描方法上的注解
                    .apis(RequestHandlerSelectors.basePackage("com.david.swagger.controller"))
                    //paths()。过滤什么路径
                    .paths(PathSelectors.ant("/david/**"))
                    .build();
        }
    

    配置是否启动Swagger

    @Bean
        public Docket docket(){
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .enable(false)//enable是否启动Swagger,如果为False,则Swagger不能再浏览器中访问
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.david.swagger.controller"))
                    .build();
        }
    

    如果只希望我的Swagger在生产环境中使用,在发布的时候不使用就需要:

    1. 判断是不是生产环境 flag = false
    2. 注入enable(flag)
    //配置了Swagger的Docket的bean实例
        @Bean
        public Docket docket(Environment environment){
    
            //设置要显示的Swagger环境
            Profiles profiles = Profiles.of("dev","test");
            //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
            boolean flag = environment.acceptsProfiles(profiles);
            System.out.println(flag);
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .enable(flag)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.david.swagger.controller"))
                    .build();
        }
    

    配置Api文档的分组

    1. .groupName(“david”)

    2. 配置多个分组,多个docket实例

      @Bean
      public Docket docket1(){
          return new Docket(DocumentationType.SWAGGER_2).groupName("豪侠");
      }
      @Bean
      public Docket docket2(){
          return new Docket(DocumentationType.SWAGGER_2).groupName("真真");
      }
      @Bean
      public Docket docket3(){
          return new Docket(DocumentationType.SWAGGER_2).groupName("超强");
      }
      
    3. 配置实体类

      package com.david.swagger.pojo;
      
      import io.swagger.annotations.Api;
      import io.swagger.annotations.ApiModel;
      import io.swagger.annotations.ApiModelProperty;
      
      //@Api(注释)
      @ApiModel("用户实体类")
      public class User {
          @ApiModelProperty("用户名")
          public String username;
          @ApiModelProperty("密码")
          public String password;
      
      }
      
    4. 编写controller

      package com.david.swagger.controller;
      
      import com.david.swagger.pojo.User;
      import io.swagger.annotations.Api;
      import io.swagger.annotations.ApiOperation;
      import io.swagger.annotations.ApiParam;
      import org.springframework.web.bind.annotation.GetMapping;
      import org.springframework.web.bind.annotation.PostMapping;
      import org.springframework.web.bind.annotation.RequestMapping;
      import org.springframework.web.bind.annotation.RestController;
      
      @RestController
      public class HelloController {
      
          @GetMapping(value = "/hello")
          public String hello(){
              return "hello";
          }
      
          //只要我们的接口中,返回值中存在实体类,他就会被扫描到Swagger中
          @PostMapping(value = "/user")
          public User user(){
              return new User();
          }
      
          //Operation接口,不是放在类上的,是方法
          @ApiOperation("Hello控制类")
          @GetMapping(value = "/hello2")
          public String hello2(@ApiParam("用户名") String username){
              return "hello"+username;
          }
      
          @ApiOperation("Post测试类")
          @PostMapping(value = "/posttest")
          public User posttest(@ApiParam("用户名") User user){
              int i = 5/0;//;模拟代码错误
              return user;
          }
      }
      

    总结swagger的作用

    通过Swagger可以给一些比较难理解的属性或者接口,增加注释信息。可以达到文档实时更新的效果,在线测试也方便理解api。swagger虽然是一个优秀的工具,但是出于安全考虑在正式发布之前关闭swagger,节省运行内存。

  • 相关阅读:
    Windows Server 2003 SP2(32位) 中文版 下载地址 光盘整合方法
    用Recycle()方法对Java对象的重要性
    Lotus中千奇百怪的 $$
    Developing a simple application using steps "User Decision" and "Mail"(1) 沧海
    沟通中的情绪管理(演讲稿) 沧海
    人只有在压力之下,才可能成功,没做一件事,都必须成功,不许言败 沧海
    什么是IDOC,以及IDOC的步骤 沧海
    VS2008 Professional Edition CHS中的deffactory.dat读取错误 沧海
    Including custom text in the step "User Decision" 沧海
    SAP Upgrade Strategy 沧海
  • 原文地址:https://www.cnblogs.com/a-xia/p/11400914.html
Copyright © 2011-2022 走看看