在微服务构建的过程中，你也许发现写的那些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没有依赖，你可以把他部署到任何服务器环境或者是你自己的机器。

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

关于@API注解

评价