Swagger是一种框架,用于自动生成Restfull API的文档,而不用开发者自己编写文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。

以下以SpringBoot 2.0.1中整合Swagger2.8.0为例.

1、Maven:

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

2、建立Swagger配置类

@Configuration // 表明它是一个配置类
@EnableSwagger2 // 开启swagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {
@Bean
public Docket productApi() {
return new Docket(DocumentationType.SWAGGER_2).select()
.apis(RequestHandlerSelectors.basePackage("com.sensetime.sensestudy.web"))// 指定扫描的包,其下Controller会生成文档
// .paths(regex("/product.*"))
.paths(PathSelectors.any()).build()//
.apiInfo(metaData());// 指定页面的基本信息 } private ApiInfo metaData() {// 设置页面的基础信息
return new ApiInfoBuilder().title("Sensestudy Server API")
.description("\"Spring Boot REST API for Sensestudy\"").version("1.0.0")
.license("Apache License Version 2.0").licenseUrl("https://www.apache.org/licenses/LICENSE-2.0\"")
.contact(
new Contact("John Thompson", "https://springframework.guru/about/", "john@springfrmework.guru"))
.build();
} @Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {// API文档页面相关资源作为静态资源,以防止被拦截处理
registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}

3、Swagger使用:相关注解

 swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。

  • @Api:修饰整个类,描述Controller的作用
  • @ApiOperation:描述一个类的一个方法,或者说一个接口
  • @ApiParam:单个参数描述
  • @ApiModel:用对象来接收参数
  • @ApiProperty:用对象接收参数时,描述对象的一个字段
  • @ApiResponse:HTTP响应其中1个描述
  • @ApiResponses:HTTP响应整体描述
  • @ApiIgnore:使用该注解忽略这个API
  • @ApiError :发生错误返回的信息
  • @ApiParamImplicitL:一个请求参数
  • @ApiParamsImplicit 多个请求参数

4、访问

http://localhost:8080/swagger-ui.html:(UI风格)

http://localhost:8080/v2/api-docs:(API风格)

参考资料:

1、SPRING BOOT RESTFUL API DOCUMENTATION WITH SWAGGER 2

2、https://blog.csdn.net/hu_zhiting/article/details/80462110

Swagger使用小记的更多相关文章

  1. gRPC+gRPC Gateway+swagger小记

    前言 本文记录了grpc-gateway的简单使用. 定义proto 先来看看最常规的 syntax = "proto3"; package protos; service Gre ...

  2. Swagger接口如何生成Html离线文档

    A very simple tool that converts Swagger Api Document to Html File. 小记Swagger接口生成Html离线文档 由来 很多人用swa ...

  3. ABP框架 - Swagger UI 集成

    文档目录 本节内容: 简介 Asp.net Core 安装 安装Nuget包 配置 测试 Asp.net 5.x 安装 安装Nuget包 配置 测试 简介 来自它的网页:“...使用一个Swagger ...

  4. [原]Paste.deploy 与 WSGI, keystone 小记

    Paste.deploy 与 WSGI, keystone 小记 名词解释: Paste.deploy 是一个WSGI工具包,用于更方便的管理WSGI应用, 可以通过配置文件,将WSGI应用加载起来. ...

  5. ABP项目中使用Swagger生成动态WebAPI

    本文是根据角落的白板报的<使用ABP实现SwaggerUI,生成动态webapi>一文的学习总结,感谢原文作者角落的白板报. 1 安装Swashbuckle.core 1.1 选择WebA ...

  6. 用Swagger生成接口文档

    Swagger简介 在系统设计的时候,各个应用之间往往是通过接口进行交互的.因此接口的定义在整个团队中就变得尤为重要.我们可以把接口的规范用接口描述语言进行描述,然后Swagger可以根据我们定义的接 ...

  7. 使用 Swagger 自动生成 ASP.NET Core Web API 的文档、在线帮助测试文档(ASP.NET Core Web API 自动生成文档)

    对于开发人员来说,构建一个消费应用程序时去了解各种各样的 API 是一个巨大的挑战.在你的 Web API 项目中使用 Swagger 的 .NET Core 封装 Swashbuckle 可以帮助你 ...

  8. 使用swagger作为restful api的doc文档生成

    初衷 记得以前写接口,写完后会整理一份API接口文档,而文档的格式如果没有具体要求的话,最终展示的文档则完全决定于开发者的心情.也许多点,也许少点.甚至,接口总是需要适应新需求的,修改了,增加了,这份 ...

  9. ASP.NET Core 中文文档 第二章 指南 (09) 使用 Swagger 生成 ASP.NET Web API 在线帮助测试文档

    原文:ASP.NET Web API Help Pages using Swagger 作者:Shayne Boyer 翻译:谢炀(kiler) 翻译:许登洋(Seay) 对于开发人员来说,构建一个消 ...

随机推荐

  1. 服务端、实时、大数据、AI计算

    服务端.实时.大数据.AI计算,各种各样的计算,计算机本质是什么,计算机的本质是 利用compute的计算速度为人提供更优的计算结果. 所以实时也好,准实时.离线.AI本质上是两个维度,实时准实时强调 ...

  2. Codeforces.542E.Playing on Graph(二分图)

    题目链接 \(Description\) 给出一个n个点m条边的无向图. 你每次需要选择两个没有边相连的点,将它们合并为一个新点,直到这张图变成了一条链. 最大化这条链的长度,或输出无解. n< ...

  3. python计算文件夹大小——os.walk

    下面提供一种利用os.walk()快捷的计算指定文件夹大小的方法 话不多说,直接上代码 简略版: import os def get_file_size(file_path, size=0): for ...

  4. 潭州课堂25班:Ph201805201 第四课:Linux的命令以及VIM的使用 (课堂笔记)

    Linux的常用命令 引入 1:如果我们要在Linux里面实现一些比如查看文件和文件夹.新建文件夹之类的操作,应该是通过什么来实现 2:讲解Linux目录树 3:讲解Linux只区分文件名,Linux ...

  5. USBWriter之后恢复磁盘大小

    USBWriter之后恢复磁盘大小的方法: 1,cmd 2,diskpart 3,list disk 4,select disk *(*你的U盘代号) (e.g:U盘为磁盘 2 ,则代号为2 ,使用命 ...

  6. Cocos Creator 的Hello World

    1,创建项目[参考来源:官方文档] 在 Dashboard 中,打开 新建项目 选项卡,选中 Hello World 项目模板. 然后在项目路径栏中指定一个新项目存放路径,路径的最后一部分就是项目文件 ...

  7. json字符串转换对象的方法1

    为了方便读者了解json的使用,读者直接粘贴下面代码看效果即可: var json1 = {'name':'小李','age':'11','sex':'女'};console.log(json1.na ...

  8. db2存储过程动态sql被截断

    编写存储过程,使用动态sql时,调试时发现变量赋值后被截断. 关键代码如下: 实现的效果是先把上下游做对比的sql语句和相关参数存入RKDM_DATA_VOID_RULE, 执行存储过程后把两个sql ...

  9. boost 1.67编译VS2017版本

    最近想系统学习并使用一下boost的asio异步网络库,所以需要编译boost库使用,下面简单介绍如何编译. 编译环境 boost1.67版本,windows 10,VS2017 下载boost 建议 ...

  10. Windows2003 内核级进程隐藏、侦测技术

    论文关键字: 内核 拦截 活动进程链表 系统服务派遣表 线程调度链 驱动程序简介    论文摘要:信息对抗是目前计算机发展的一个重要的方向,为了更好的防御,必须去深入的了解敌人进攻的招式.信息对抗促使 ...