微服务RESTful接口文档生成神器Swagger初探

在微服务构建的过程中,你也许发现写的那些restful风格的接口需要编写文档。

文档一般包括要输入哪些参数,哪些参数是必填的,哪些是选填的。还有返回结果的格式以及结果示例。

也许你可以通过在git上写markdown文档来做这些事情。

但每个接口对应的文档地址这些对应关系你又需要关心。

通过swagger,这一切你都不需要做了。

在你编写自己的restful接口的时候,只需要添加一些annotation就可为你自动的生成接口文档。你上面的那些内容都为你自动生成。

甚至连简单的功能测试表单都为你做好了。

总之,你过去需要手来搞的,这里一切为你自动化。

说了这么多,那么怎么使用呢?

目录:

Maven 依赖

@EnableSwagger2 使用

@Api 使用

@ApiOperation && @ApiParam 使用

Docket && ApiInfo 使用

swagger-ui文档首页

swagger页面展示

这里我们以spring boot 为例,

Maven:

首先你需要引入maven依赖:

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

@EnableSwagger2

然后springboot上的application类上加上一行注解:

@EnableDiscoveryClient
@SpringBootApplication
@EnableSwagger2 //就是这一行
public class BaseApplication {

然后你就可以在你的rest controller的类上和方法上添加swagger注解来描述你的接口了。

@Api

像下面这样:

@RestController
@Api(tags={"DEMO-SERVICE"})
public class DemoController extends BaseController {

@ApiOperation && @ApiParam

然后就在你的具体的方法上加上:

@ApiOperation(value="计算结果", notes = "根据参数a、b和c计算(a+b)*c的结果")
@RequestMapping(value = "/demo", method = RequestMethod.GET)
public Integer demo(@RequestParam @ApiParam(name="a",value="参数a",required=true)Integer a,
               @RequestParam  @ApiParam(name="b",value="参数b",required=true)Integer b,
               @RequestParam @ApiParam(name="c",value="参数c",required=true) Integer c) {

关于@API注解

在Swagger Annotation中:

@API表示一个开放的API,可以通过description简要描述该API的功能。 在一个@API下,可有多个@ApiOperation,表示针对该API的CRUD操作。在

ApiOperation Annotation中可以通过value,notes描述该操作的作用,response描述正常情况下该请求的返回对象类型。 在一个ApiOperation下,可以通过ApiResponses描述该API操作可能出现的异常情况。

ApiParam用于描述该API操作接受的参数类型。

Docket && ApiInfo

你也许发现了,现在给方法写了文档,api的整体说明现在并没有。

你还需要配置api的说明文档。你只需要通过@Bean配置一个ApiInfo就可以了。

@Bean
public Docket createRestApi() {
   return new Docket(DocumentationType.SWAGGER_2)
         .groupName("DEMO-SERVICE")
         .genericModelSubstitutes(DeferredResult.class)
         .useDefaultResponseMessages(false)//禁用默认的响应
         .globalResponseMessage(RequestMethod.POST,          //根据自己的需要设计响应           
               Arrays.asList(new ResponseMessageBuilder()
                           .code(500)
                           .message("500 message")
                           .responseModel(new ModelRef("Error"))
                           .build(),
                     new ResponseMessageBuilder()
                           .code(403)
                           .message("Forbidden!")
                           .build()))
         .forCodeGeneration(false)
         .pathMapping("/")// base,最终调用接口后会和paths拼接在一起
         .select() // 选择那些路径和api会生成document
         .paths(or(regex("/.*")))//(对指定路径进行监控)过滤的接口
         .build()
         .apiInfo(apiInfo());   //这里配置apiinfo
}

apiinfo是下面这样:

private ApiInfo apiInfo(){
   ApiInfo apiInfo = new ApiInfoBuilder()
         .title("Demo-Service服务的RESTful API文档")
         .description("该文档使用Swagger2构建,更多详细信息,请访问http://swagger.io")
         .license(null)
         .licenseUrl(null)
         .contact(new Contact("importsource", "", "importsource@gmail.com"))
         .version("1.0")
         .build();
   return apiInfo;
}

swagger-ui页面链接配置

现在基本的文档都写好了。

也许你还在想,我的文档页面是在哪里指定的呢?

很简单,只需要在你的controller中加入下面这样一个方法:

/**
 * swagger-ui文档首页
 * @return
 */
@ApiIgnore
@RequestMapping("/info")
public ModelAndView swaggerInfo() {
   String url="redirect:swagger-ui.html";
   return new ModelAndView(url);
}

swagger页面展示

好了,一切都好了。现在我们去swagger的页面看看吧:

你输入参数后,点击try it out按钮,马上就会为你展示出结果以及请求url等等。

没错,一个文档已经为你写好了。而且自带了功能测试界面,让过去你通过浏览器手动输入参数测试的步骤都为你考虑到了。

评价

Swagger可以充当前后端交流的重要桥梁,方便快捷。很实用。

Swagger项目允许你生产,显示和消费你自己的RESTful服务。不需要代理和第三方服务。是一个依赖自由的资源集合,它能通过Swagger API动态的生成漂亮的文档和沙盒,因为Swagger UI没有依赖,你可以把他部署到任何服务器环境或者是你自己的机器。

原文发布于微信公众号 - ImportSource(importsource)

原文发表时间:2017-01-06

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏IT笔记

SpringBoot开发案例之整合Swagger篇

前段时间整合过的一个支付服务,由于使用了Spring Boot快速开发,但是又懒得写详细的文档介绍,便顺手就把Swagger整合进来了,对支付服务进行分组API...

2877
来自专栏xingoo, 一个梦想做发明家的程序员

Apache虚拟主机-解惑篇

    有很多平时喜欢钻研的童鞋会发现,为什么有时候自己访问某XXse网站时,总是更新IP地址,内容却与以前一样。这个时候就要了解虚拟主机的概念了。了解这个概...

3135
来自专栏乐沙弥的世界

Apache httpd 2.4 alias 别名配置

Web网站别名配置是被经常使用的一个特性。这个功能实际上是为站点URI定义一个路径映射关系,其配置和使用也较为简单。以下是基于CentOS 7下实现alias的...

921
来自专栏LIN_ZONE

windows Apache服务器简单配置虚拟域名(转载)

#<VirtualHost *:80> #    ServerAdmin webmaster@dummy-host2.example.com #    Docu...

1232
来自专栏菩提树下的杨过

mac 10.9.4下配置apache

启动后,访问 http://localhost/ 应该能看到"It works!"的初始页面,如果对初始页面的内容感到好奇,可以打开"/etc/apache2/...

792
来自专栏运维技术迷

WAMP配置虚拟主机

1、点击桌面右下角的WAMP图标,依次打开Apache—>httpd.conf ? 2、打开httpd.conf配置文件,ctrl+f进行搜索,输入#Inc...

2.1K5
来自专栏battcn

一起来学SpringBoot | 第十一篇:集成Swagger在线调试

随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、前后端分离的形态,而且前端和后端在各自的技术道路上越走越远。

1113
来自专栏carven

实习笔记2--20160121

890
来自专栏小尘哥的专栏

美化一下你的API文档吧(springboot集成swagger及遇到的问题)

微服务的流行提供了诸多的方便,随着也带来了N多的API,而swagger2正是一个对API管理的很好的“工具”,本文主要介绍springboot对swagger...

2383
来自专栏IT笔记

SpringBoot开发案例之整合Swagger篇

前段时间整合过的一个支付服务,由于使用了Spring Boot快速开发,但是又懒得写详细的文档介绍,便顺手就把Swagger整合进来了,对支付服务进行分组API...

4355

扫码关注云+社区

领取腾讯云代金券