Swagger详解

Swagger 这一个文章就够了

Swagger快速理解

Swagger:The Best APIs are Built with Swagger Tools

。Swagger可以定义一个标准的RESTful风格的API，与语言无关，是一个API的规范。

Swagger官网：http://swagger.io

GitHub地址：https://github.com/swagger-api

这里，提到Swagger就不得不说说Springfox,Springfox是一个开源的API Doc的框架， 它的前身是swagger-springmvc，可以将我们的Controller中的方法以文档的形式展现。官方定义为： Automated JSON API documentation for API’s built with Spring。Swagger和SpringFox到底什么关系呢？

- Swagger Spec 是一个规范。

- Swagger Api 是 Swagger Spec 规范 的一个实现，它支持 jax-rs, restlet, jersey 等等。

- Springfox libraries 是 Swagger Spec 规范 的另一个实现，专注于 spring 生态系统。

- Swagger.js and Swagger-ui 是 javascript 的客户端库，能消费该规范。

- springfox-swagger-ui 仅仅是以一种方便的方式封装了 swagger-ui ，使得 Spring 服务可以提供服务。

1

2

3

4

5

在官网的Tools菜单中，我们会方法里面有很多工具或者系统的介绍。其中我们最常用的两个工具一个是swagger editor、一个是swagger UI。

Swagger Edit

Swagger Edit主要是用来设计，描述API的工具，主要是提供给接口开发人员使用的。swagger editor 编译完接口文档之后呢，会形成一个文件。

Swagger UI

Swagger UI允许任何人 - 无论是您的开发团队还是最终消费者 - 在没有任何实现逻辑的情况下可视化和与API资源交互。 它是从您的OpenAPI规范自动生成的，其可视化文档使后端实现和客户端消费变得容易。

swagger-editor主要是编写api接口文档，但需要配合swagger-ui来查看，里面的代码格式为yaml，但编辑后可以导出yml/json文件

Swagger Edit和Swagger UI 互补性存在

如果只是手动写api文档，人工查看那么就做部署Swagger Edit和Swagger UI就可以了。

通过下面命令下载两个项目：

mkdir swagger

chmod 777 swagger

cd swagger

git clone https://github.com/swagger-api/swagger-editor.git

git clone https://github.com/swagger-api/swagger-ui.git

1

2

3

4

5

PS: UI和Edit都是NodeJS的开发，一次需要先安装Nodejs的运行环境。

下载nodejs的安装包，具体要去网站上查看最新版本

wget https://nodejs.org/dist/v6.11.3/node-v6.11.3.tar.gz

tar -zxvf node-v6.11.3.tar.gz

mv node-v6.11.3 /user/local/node

cd /usr/local/node

./configure

make

make install

node -v

1

2

3

4

5

6

7

8

9

先安装http-server

npm install -g http-server

1

-g表示全局

启动ui和edit

http-server –p 12321 swagger-editor

http-server –p 12421 swagger-ui

cd swagger-ui/dist

vim index.html

1

2

3

4

5

6

进入index.html后，修改如下字段

...

const ui = SwaggerUIBundle({

//url: "http://petstore.swagger.io/v2/swagger.json",

url: "http://127.0.0.1:12321/json/1.json",

dom_id: '#swagger-ui',

...

1

2

3

4

5

6

然后保存后

打开浏览器：

swaggerEdit ： http://127.0.0.1：12321

swaggerUI：http://127.0.0.1：12421/dist

1

2

Maven插件在原生工程里面快速生产Json的api文件（转自：https://blog.csdn.net/doctor_who2004/article/details/50816208）

在maven工程的pom文件中，放入如下插件：

<build>

        <plugins>

            <plugin>

                <groupId>org.apache.maven.plugins</groupId>

                <artifactId>maven-javadoc-plugin</artifactId>

                <configuration>

                    <charset>UTF-8</charset>

                    <docencoding>UTF-8</docencoding>

                    <failOnError>false</failOnError>

                </configuration>

            </plugin>

            <plugin>

                <groupId>com.github.kongchen</groupId>

                <artifactId>swagger-maven-plugin</artifactId>

                <configuration>

                    <apiSources>

                        <apiSource>

                            <springmvc>false</springmvc>

                            <locations>com.doctor.demo</locations>

                            <schemes>http,https</schemes>

                            <host>petstore.swagger.wordnik.com</host>

                            <basePath>/api</basePath>

                            <info>

                                <title>Swagger Maven Plugin Sample</title>

                                <version>v1</version>

                                <description>This is a sample for swagger-maven-plugin</description>

                                <termsOfService>

                                    http://www.github.com/kongchen/swagger-maven-plugin

                                </termsOfService>

                                <contact>

                                    <email>kongchen@gmail.com</email>

                                    <name>Kong Chen</name>

                                    <url>http://kongch.com</url>

                                </contact>

                                <license>

                                    <url>http://www.apache.org/licenses/LICENSE-2.0.html</url>

                                    <name>Apache 2.0</name>

                                </license>

                            </info>

                            Support classpath or file absolute path here. 1) classpath e.g: "classpath:/markdown.hbs", "classpath:/templates/hello.html" 2) file e.g: "${basedir}/src/main/resources/markdown.hbs", "${basedir}/src/main/resources/template/hello.html"

                            <templatePath>${basedir}/templates/strapdown.html.hbs</templatePath>

                            <outputPath>${basedir}/generated/document.html</outputPath>

                            <swaggerDirectory>generated/swagger-ui</swaggerDirectory>

                        </apiSource>

                    </apiSources>

                </configuration>

                <executions>

                    <execution>

                        <phase>compile</phase>

                        <goals>

                            <goal>generate</goal>

                        </goals>

                    </execution>

                </executions>

            </plugin>

           

        </plugins>

    </build>

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

Swagger和SpringMVC项目的整合（转自：https://www.cnblogs.com/jtlgb/p/6734177.html）

引入依赖

<!-- swagger-springmvc -->

    <dependency>

        <groupId>com.mangofactory</groupId>

        <artifactId>swagger-springmvc</artifactId>

        <version>1.0.2</version>

    </dependency>

    <dependency>

        <groupId>com.mangofactory</groupId>

        <artifactId>swagger-models</artifactId>

        <version>1.0.2</version>

    </dependency>

    <dependency>

        <groupId>com.wordnik</groupId>

        <artifactId>swagger-annotations</artifactId>

        <version>1.3.11</version>

    </dependency>

    <!-- swagger-springmvc dependencies -->

    <dependency>

        <groupId>com.google.guava</groupId>

        <artifactId>guava</artifactId>

        <version>15.0</version>

    </dependency>

    <dependency>

        <groupId>com.fasterxml.jackson.core</groupId>

        <artifactId>jackson-annotations</artifactId>

        <version>2.4.4</version>

    </dependency>

    <dependency>

        <groupId>com.fasterxml.jackson.core</groupId>

        <artifactId>jackson-databind</artifactId>

        <version>2.4.4</version>

    </dependency>

    <dependency>

        <groupId>com.fasterxml.jackson.core</groupId>

        <artifactId>jackson-core</artifactId>

        <version>2.4.4</version>

    </dependency>

    <dependency>

        <groupId>com.fasterxml</groupId>

        <artifactId>classmate</artifactId>

        <version>1.1.0</version>

    </dependency>

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

Swagger配置

Swagger的配置实际上就是自定义一个Config类，通过java编码的方式实现配置。代码如下：

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;

import com.mangofactory.swagger.models.dto.ApiInfo;

import com.mangofactory.swagger.plugin.EnableSwagger;

import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

/**

* Created by xiaohui on 2016/1/14.

*/

@Configuration

@EnableSwagger

@EnableWebMvc

public class SwaggerConfig {

    private SpringSwaggerConfig springSwaggerConfig;

    /**

    * Required to autowire SpringSwaggerConfig

    */

    @Autowired

    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)

    {

        this.springSwaggerConfig = springSwaggerConfig;

    }

    /**

    * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc

    * framework - allowing for multiple swagger groups i.e. same code base

    * multiple swagger resource listings.

    */

    @Bean

    public SwaggerSpringMvcPlugin customImplementation()

    {

        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)

                .apiInfo(apiInfo())

                .includePatterns(".*?");

    }

    private ApiInfo apiInfo()

    {

        ApiInfo apiInfo = new ApiInfo(

                "My Apps API Title",

                "My Apps API Description",

                "My Apps API terms of service",

                "My Apps API Contact Email",

                "My Apps API Licence Type",

                "My Apps API License URL");

        return apiInfo;

    }

}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

在springmvc的配置文件中加入以下配置即可。

<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />

1

到目前为止，我们已经完成了对所有接口方法的扫描解析功能，那解析得到什么内容呢？这需要我们自定义，自定义操作的对象就是接口方法。先看段代码：

/**

* 根据用户名获取用户对象

* @param name

* @return

*/

@RequestMapping(value="/name/{name}", method = RequestMethod.GET)

@ResponseBody

@ApiOperation(value = "根据用户名获取用户对象", httpMethod = "GET", response = ApiResult.class, notes = "根据用户名获取用户对象")

public ApiResult getUserByName(@ApiParam(required = true, name = "name", value = "用户名") @PathVariable String name) throws Exception{

    UcUser ucUser = ucUserManager.getUserByName(name);

    if(ucUser != null) {

        ApiResult<UcUser> result = new ApiResult<UcUser>();

        result.setCode(ResultCode.SUCCESS.getCode());

        result.setData(ucUser);

        return result;

    } else {

        throw new BusinessException("根据{name=" + name + "}获取不到UcUser对象");

    }

}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

上述代码是Controller中的一个方法，@ApiOperation注解对这个方法进行了说明，@ApiParam注解对方法参数进行了说明。关于这两个注解的使用，可以参看源码。这样子，Swagger就可以扫描接口方法，得到我们自定义的接口说明内容。

说明：

其中@ApiOperation和@ApiParam为添加的API相关注解，个参数说明如下：

@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”；其他参数可参考源码；

@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”

Swagger-UI配置

Swagger扫描解析得到的是一个json文档，对于用户不太友好。下面介绍swagger-ui，它能够友好的展示解析得到的接口说明内容。

从https://github.com/swagger-api/swagger-ui 获取3.0版本以下，2.0版本以上。其所有的 dist 目录下东西放到需要集成的项目里，本文放入 src/main/webapp/WEB-INF/swagger/ 目录下。

修改swagger/index.html文件，默认是从连接http://petstore.swagger.io/v2/swagger.json获取 API 的 JSON，这里需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式，{}中的值根据自身情况填写。比如我的url值为：http://localhost:8083/arrow-api/api-docs

因为swagger-ui项目都是静态资源，restful形式的拦截方法会将静态资源进行拦截处理，所以在springmvc配置文件中需要配置对静态文件的处理方式。

//所有swagger目录的访问，直接访问location指定的目录

<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/"/>

1

2

OK！大功告成，打开浏览器直接访问swagger目录下的index.html文件，即可看到接口文档说明了

参考：

https://blog.csdn.net/kinginblue/article/details/78513029

https://www.jianshu.com/p/52acab692a79

https://blog.csdn.net/doctor_who2004/article/details/50816208

https://www.cnblogs.com/jtlgb/p/6734177.html

©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 206,126评论 6赞 481
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 88,254评论 2赞 382
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 152,445评论 0赞 341
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 55,185评论 1赞 278
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 64,178评论 5赞 371
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 48,970评论 1赞 284
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 38,276评论 3赞 399
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 36,927评论 0赞 259
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 43,400评论 1赞 300
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,883评论 2赞 323
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,997评论 1赞 333
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 33,646评论 4赞 322
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 39,213评论 3赞 307
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 30,204评论 0赞 19
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,423评论 1赞 260
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 45,423评论 2赞 352
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 42,722评论 2赞 345

推荐阅读更多精彩内容