Swagger学习记录 - Githubissues

Swagger是一组开源项目，其中主要要项目如下：

Swagger-tools

提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。

Swagger API Spec/Open API Spec

Swagger API Spec是Swagger用来描述Rest API的语言，类似于描述Web服务的WSDL，API描述文件的形式为yml或者json。 Swagger API Spec对你Rest API的每一个操作的请求消息的参数（Path,Query,Body,Form），响应消息的状态码和消息体的json结构都进行了详细的描述。不仅可以供给使用API的开发者学习，而且是对Rest API接口的形式化的抽象。

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 UI：http://petstore.swagger.io/ 但前端资源都被打成了jar包，对外不可见。

Springfox-swagger

整合spring boot，可以使用注解进行swagger的api描述，生成API描述文件，再交由swagger-ui实现展示。

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox.version}</version>
</dependency>
<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox.version}</version>
</dependency>

配置文件：

@Configuration
@EnableSwagger2
public class Swagger2Configuration {
...

参考文档：Spring boot中使用springfox来生成Swagger Specification小结

Swagger-codegen

一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。它是个Jar包，可以直接在windows上使用。使用关键步骤：

java -jar swagger-codegen-cli-2.2.1.jar generate -i http://petstore.swagger.io/v2/swagger.json -l csharp

更多见官方指导之Generation Code。

Swagger-editor

可让使用者在浏览器里以YAML格式编辑Swagger API规范并实时预览文档。可以生成有效的API描述文件，并用于所有Swagger工具（代码生成、文档等等）中。

SWAGGER EDITOR Swagger在线编辑器

Swagger Editor的安装也很方便，下载最新的发布版，然后解压到文件夹，用HTTP Server将静态文件加载起来，下面是安装node.js的http server并跑起来的指令

npm install -g http-server
wget https://github.com/swagger-api/swagger-editor/archive/v3.0.16.zip
unzip swagger-editor.zip
http-server -p 8080 swagger-editor

http server启动后，就可以在浏览器中输入地址进行编辑了。将yml或者json的API描述文件实时转为swagger-UI。

如何将Swagger整合到自己的spring boot项目中？

实时生成API描述文件，然后自定义Swagger UI。

window.swaggerUi = new SwaggerUi({
    url: 'http://petstore.swagger.io/v2/swagger.json', // url of specification
    dom_id: 'swagger-ui-container' //id of element where to render swagger-ui
…
});

尝试后继续更新。

参考 Swagger官网 GitHub：Swagger Swagger规范 SpringFox官网 GitHub：SpringFox Spring Boot & Swagger UI 使用swagger作为restful api的doc文档生成

SherryLang / javalearning

Swagger学习记录 #15