swagger入门

一.Swagger简介

image.png

说白了就是接口开发的一套标准规范及其衍生物，通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

    作为Java届服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。

二.框架说明及使用

1.说明

现在SWAGGER官网主要提供了几种开源工具，提供相应的功能。可以通过配置甚至是修改源码以达到你想要的效果。

image.png

Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多种语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

image.png

Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

Swagger Inspector: 感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

Swagger Hub

三.基于Spring框架的Swagger流程应用

1.导入依赖

2.创建Swagger2配置类

3.在spring-web.xml文件中配置创建对象：

4.在controller的类中进行相关的配置：

5）部署工程，访问路径：

格式：http://服务器ip:端口/项目名称/swagger-ui.html

http://服务器ip:端口/项目名称/v2/api-docs可以看到接口json描述文件，上面的HTML其实就是通过模板加json数据渲染生成的。

四、swagger常用注解说明：（更多）

五.生成adoc、html、PDF格式文档（重头戏）

1.adoc格式

首先添加依赖

要配两个私有的仓库

参考文档

运行swagger2markup-maven-plugin插件命令，即可生成adoc格式文档

同样上面文档也可以用java代码生成，写个单元测试，但是springfox-swagger2和springfox-swagger-ui版本要换成2.9.2，不然会出现问题。

2.HTML和PDF格式

配置参考

最后执行 mvn generate-resources命令即可

PDF文档：

中文乱码参考

生成顺序：json描述文件-》adoc格式文档-》HTML、PDF文档