swagger的学习要点

超、凢脫俗 2024-03-17 10:02 10阅读 0赞

>  *  了解swagger的作用和概念
>  *  了解前后端分离
>  *  在SpringBoot中集成Swagger

> ## swagger？（文档、测试） ##
> 
>  *  swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
>  *  接口文档自动在线生成。
>  *  功能测试。

> ## Swagger包含的工具集： ##
> 
>  *  Swagger-tools：提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger1.2文档转换成Swagger2.0文档等功能。
>  *  Swagger-core：用于Java/Scala的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…）、Servlets和Play框架进行集成。
>  *  Swagger-js：用于JavaScript的Swagger实现。
>  *  Swagger-node-express：Swagger模块，用于node.js的Express web应用框架。
>  *  Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
>  *  Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码

> ## swagger的使用步骤： ##
> 
> 1.  引入pom的相关依赖
> 2.  在代码中加入相应的配置，新建config包，写入swaggerConfig配置类
> 3.  在basePackage指定的路径下使用swagger（使用api注解）
> 4.  启动项目，浏览器打开http://ip:port/swagger-ui.html进行测试

swagger 的相关依赖：

</dependency>
      <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
    
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>

## SpringBoot整合Swagger ##

import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration//设置该类为spring配置类
    @EnableSwagger2//开户swagger2
    public class SwaggerConfig {
    
        /**
         * 创建API应用
         * apiInfo() 增加API相关信息
         * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
         * 本例采用指定扫描的包路径来定义指定要建立API的目录。
         * .apis
         *    RequestHandlerSelectors 配置swagger扫描接口的方式
         *       basePackage() 指定要扫描哪些包
         *       any() 全部都扫描
         *       none() 全部不扫描
         *       withClassAnnotation() 扫描类上的注解 参数是一个注解的反射对象
         *       withMethodAnnotation() 扫描包上的注解
         *  .paths
         *    PathSelectors 路径扫描接口
         *       ant 配置以xxx 开头的路径
         *
         * @return
         */
    
        @Bean //设置该方法的返回值为spring管理的bean
        public Docket restApi() {//配置了swagger的docket的bean实例
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("标准接口")
                    .apiInfo(apiInfo("Spring Boot中使用Swagger2构建RESTful APIs", "1.0"))
                    .useDefaultResponseMessages(true)
                    .forCodeGeneration(false)
                    .select()
                    
                    //RequestHandlerSelectors配置要扫描接口的方式
                    .apis(RequestHandlerSelectors.basePackage("com.example.learning.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        /**
         * 创建该API的基本信息（这些基本信息会展现在文档页面中）
         * 访问地址：http://ip:port/swagger-ui.html
         *
         * @return
         */
        private ApiInfo apiInfo(String title, String version) {//配置Swagger页面信息
            return new ApiInfoBuilder()
                    .title(title)
                    .description("swagger")
                    .termsOfServiceUrl("https://swagger.io")
                    .contact("swagger")
                    .version("1.0")
                    .build();//构建者模式，快速构建一个对象
        }
    }

controller层使用swagger

import com.fasterxml.jackson.databind.ObjectMapper;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import io.swagger.annotations.ApiParam;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.RequestBody;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    import javax.annotation.Resource;
    import java.io.IOException;
    import java.util.Map;
    
    @RestController
    @RequestMapping("/api")
    @Api(tags = "标准演示接口")
    public class ApiController {
        @Resource
        private ObjectMapper mapper;
    
        @PostMapping("/ps")
        @ApiOperation(value = "接受json参数", notes = "演示json参数是否接受成功")
        public String post(@ApiParam(name = "接收json参数", defaultValue = "{}")
                               @RequestBody String json) throws IOException {
            Map map = mapper.readValue(json, Map.class);
            System.out.println(map);
            return json;
        }
    }

> ## swagger的相关注解： ##
> 
>  *  **@Configuration：表明这是一个配置类**
>  *  **@EnableSwagger2：开启Swagger2**
>  *  @Api：放在类上，说明该类的作用。
>  *  @ApiOperation：放在方法上，说明该方法的作用。
>  *  @ApiImplicitParams：用在方法上包含一组参数说明。
>     
>      *  code：数字，例如400
>      *  message：信息，例如“请求参数没填好”
>      *  response：抛出异常的类
>  *  @ApiImplicitParam：用来注解来给方法入参增加说明，一个请求能数。
>  *  @ApiResponses：用于表示一组响应。
>  *  @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
>  *  @ApiModel：用对象来接收参数，描述一个Model的信息（一般用于在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
>  *  @ApiModelProperty：用对象接收参数时，描述对象的一个字段
>  *  @ApiIgnore：使用该注解忽略这个API
>  *  @ApiError ：发生错误返回的信息