API编写利器——swagger简记

  • pqdong 

API编写利器——swagger简记

第一章:swagger简介

1.什么是Swagger

  • Swagger是一个规范且完整的框架,提供描述、生产、消费和可视化RESTful Web Service。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。
  • Swagger是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。
  • Swagger 可以贯穿于整个 API 生态,如 API 的设计、编写 API 文档、测试和部署。

2.Swagger组成

  • Swagger-editor 是一种编辑器,用于编写 Swagger 文档,还支持文档实时检测、API 调试等功能。
  • Swagger-ui 是一种 UI 渲染工具,用于渲染 Swagger 文档,以提供美观的 API 界面,支持调试。
  • Swagger-codegen 是一种代码生成器,可基于 Swagger 文档,来构建服务器端 stub 和 客户端 SDK。

3.Swagger作用

  • Swagger 可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API。
  • Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
  • Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
  • 接口的文档在线自动生成和调试测试

4.为什么使用Swagger:

  • 规范统一,包括参数方法名等规范统一便于前后端对接
  • 可视化,在可视化环境下直接修改生成渲染,使API文档更加美观
  • 自动生成

第二章:Swagger的使用

1.使用说明

  • 如果 RESTful API 接口已经开发完成,则可以用 Swagger-editor 来编写 API 文档( yaml 文件 或 json 文件),然后通过 Swagger-ui 来渲染该文件,以非常美观的形式将你的 API 文档,展现给你的团队或者客户。
  • 如果 RESTful API 还未开始,可以使用 Swagger 生态,来设计和规范 API,以 Annotation (注解)的方式给源代码添加额外的元数据。这样,Swagger 就可以检测到这些元数据,自动生成对应的 API 描述信息。也就是说,Swagger 支持自动生成 API 文档。
  • 开发过程中可以使用Swagger-ui来调试测试API接口的正确性
  • swagger可以集成swagger2markup插件直接生成API文档

2.Swagger-editor使用:可以直接去官网下载,因为现在还未使用所以暂不介绍

3.Swagger-ui使用

  • maven添加项目依赖,自行选择版本,如果项目使用spring boot框架,可以选择相应版本
    <dependency>
    	<groupId>io.springfox</groupId>
    	<artifactId>springfox-swagger-ui</artifactId>
    	<version>2.6.1</version>
    </dependency>
    
    <dependency>
    	<groupId>io.springfox</groupId>
    	<artifactId>springfox-swagger2</artifactId>
    	<version>2.6.1</version>
    </dependency>
  • 自定义对Swagger的配置
    package com.swaggerTest;
    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.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    /**
     * Swagger2配置类
     * 在与spring boot集成时,放在与Application.java同级的目录下。
     * 通过@Configuration注解,让Spring来加载该类配置。
     * 再通过@EnableSwagger2注解来启用Swagger2。
     */
    @Configuration
    @EnableSwagger2
    public class Swagger2 {
        
        /**
         * 创建API应用
         * apiInfo() 增加API相关信息
         * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
         * 本例采用指定扫描的包路径来定义指定要建立API的目录。
         * 
         * @return
         */
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.swaggerTest.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
        
        /**
         * 创建该API的基本信息(这些基本信息会展现在文档页面中)
         * 访问地址:http://项目实际地址/swagger-ui.html
         * @return
         */
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Spring Boot中使用Swagger2构建RESTful APIs")
                    .description("更多请关注http://www.baidu.com")
                    .termsOfServiceUrl("http://www.baidu.com")
                    .contact("sunf")
                    .version("1.0")
                    .build();
        }
    }
    
  • 配置需要解析的接口方法
    @ApiOperation(value = "删除通道配置")
    @RequestMapping(value = {"/sys/base/channel/delete"}, method = RequestMethod.POST)
    public ApiResult deleteChannel(Integer pkId){
        channelFacade.deleteOneChannel(pkId);
        //删除此条通道在通道-通道组中的记录
        Integer channelGroupPkId = channelFacade.findOneChannelOfChannelGroup(pkId);
        channelFacade.deleteOneChannelOfChannelGroup(channelGroupPkId,pkId);
        return ApiResult.ok();
    }
  • Swagger使用的注解及其说明:
    @Api:用在类上,说明该类的作用。
    @ApiOperation:注解来给API增加方法说明。
    @ApiImplicitParams : 用在方法上包含一组参数说明。
    @ApiImplicitParam:用来注解来给方法入参增加说明。
    @ApiResponses:用于表示一组响应
    @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
          code:数字,例如400
          message:信息,例如"请求参数没填好"
          response:抛出异常的类   
    
    @ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
    @ApiModelProperty:描述一个model的属性(方便可以直接生成API接口文档)
    @ApiParam:path或param参数描述接口参数
  • 最后启动spring boot项目,在浏览器中访问http://localhost:8080/swagger-ui进行调试等

第三章:Swagger-ui常见问题和参数状态

参考博客:

https://www.jianshu.com/p/f76d2c421422?utm_campaign=maleskine

https://blog.csdn.net/sanyaoxu_2/article/details/80555328

https://www.cnblogs.com/JoiT/p/6378086.html

https://blog.csdn.net/lamp_yang_3533/article/details/80114083

 

发表评论

电子邮件地址不会被公开。 必填项已用*标注