zhihu-spider之Swagger——zhihu-spider开源项目使用技术详解（其二）

zhihu-spider之Swagger——zhihu-spider开源项目使用技术详解（其二）

1.Swagger简介

  Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件,它能够允许我们在一个HTML5 Web页面中，对API进行文档化和交互。

  Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

  官方地址：https://swagger.io/

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

  官方注解文档：http://docs.swagger.io/swagger-core/apidocs/index.html

2.集成Swagger-Spring MVC

1>.添加依赖

//gradle依赖如下

compile "io.springfox:springfox-swagger2:2.6.1"
compile "io.springfox:springfox-swagger-ui:2.6.1"

//maven依赖如下

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>

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

2>.增加配置

//Swagger配置文件SwaggerDocumentationConfig.java

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@javax.annotation.Generated(value = "io.swagger.codegen.languages.SpringCodegen", date = "2017-06-06T20:25:53.736+08:00")
/**
 * Swagger配置
 * 
 * @author sunzc
 *
 *         2017年6月10日 上午9:42:28
 */
@Configuration
@EnableSwagger2
public class SwaggerDocumentationConfig {

    ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("WeiYou Zhihu")
                .description(
                        "No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)")
                .license("").licenseUrl("http://unlicense.org").termsOfServiceUrl("").version("1.0.0")
                .contact(new Contact("", "", "")).build();
    }

    @Bean
    public Docket customImplementation() {
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("com.wei.you.zhihu.spider.controller")).build()
                .directModelSubstitute(org.joda.time.LocalDate.class, java.sql.Date.class)
                .directModelSubstitute(org.joda.time.DateTime.class, java.util.Date.class).apiInfo(apiInfo());
    }

}

3.Swagger文档编辑

  编辑工具：http://editor.swagger.io/

  文档语法：https://swagger.io/specification/

1>.Swagger-Editor编辑生成的swagger.yml源码

swagger: '2.0'
info:
  title: WeiYou Zhihu
  version: 1.0.0
host: '127.0.0.1:8080'
schemes:
  - http
basePath: /weiyou/zhihu/v1/
produces:
  - application/json
paths:
  /user/list:
    get:
      tags: 
        - ZhihuUser
      summary: 用户展示
      description: 知乎用户列表
      parameters:
        - name: start
          in: query
          type: number
          description: 起始页
          required: true
        - name: size
          in: query
          type: number
          description: 页展示数
          required: true
        - name: filter
          in: query
          type: string
          description: 过滤条件
          required: false
      responses:
        '200':
          description: 返回应用服务器的请求列表
          schema:
            $ref: '#/definitions/ResultDTO'
        default:
          description: 返回错误信息
  /user/add:
    post:
      tags: 
        - ZhihuUser
      summary: 用户新增
      description: 用户新增
      parameters:
        - name: name
          in: query
          type: string
          description: 用户名
          required: true
        - name: sex
          in: query
          type: string
          description: 用户性别
          required: false
        - name: agentId
          in: query
          type: string
          description: 应用agentId
          required: true
        - name: spanId
          in: query
          type: number
          description: 调用栈spanId
          required: true
      responses:
        '200':
          description: 返回应用服务器的请求列表
          schema:
            $ref: '#/definitions/ResultDTO'
        default:
          description: 返回错误信息
  /user/edit:
    put:
      tags: 
        - ZhihuUser
      summary: 用户修改
      description: 用户修改
      parameters:
        - name: id
          in: query
          type: string
          description: 用户id
          required: true
        - name: name
          in: query
          type: string
          description: 用户名
          required: true
        - name: sex
          in: query
          type: string
          description: 用户性别
          required: false
        - name: agentId
          in: query
          type: string
          description: 应用agentId
          required: true
        - name: spanId
          in: query
          type: number
          description: 调用栈spanId
          required: true
      responses:
        '200':
          description: 返回应用服务器的请求列表
          schema:
            $ref: '#/definitions/ResultDTO'
        default:
          description: 返回错误信息
  /user/delete:
    delete:
      tags: 
        - ZhihuUser
      summary: 用户删除
      description: 用户删除
      parameters:
        - name: id
          in: query
          type: string
          description: 用户id
          required: true
      responses:
        '200':
          description: 返回应用服务器的请求列表
          schema:
            $ref: '#/definitions/ResultDTO'
        default:
          description: 返回错误信息
  /question/list:
    get:
      tags: 
        - ZhihuQuestion
      summary: 知乎问题
      description: 知乎问题列表
      parameters:
        - name: start
          in: query
          type: number
          description: 起始页
          required: true
        - name: size
          in: query
          type: number
          description: 页展示数
          required: true
        - name: filter
          in: query
          type: string
          description: 过滤条件
          required: false
      responses:
        '200':
          description: 应用服务器的应用信息列表
          schema:
            $ref: '#/definitions/ResultDTO'
        default:
          description: 返回错误信息
  /question/add:
    post:
      tags: 
        - ZhihuQuestion
      summary: 知乎问题新增
      description: 知乎问题新增
      parameters:
        - name: question
          in: query
          type: string
          description: 问题名称
          required: true
        - name: questionDestion
          in: query
          type: string
          description: 问题详情
          required: false
        - name: author
          in: query
          type: string
          description: 问题提出者
          required: true
        - name: url
          in: query
          type: string
          description: 问题url
          required: true
      responses:
        '200':
          description: 应用服务器的应用信息列表
          schema:
            $ref: '#/definitions/ResultDTO'
        default:
          description: 返回错误信息
  /question/delete:
    delete:
      tags: 
        - ZhihuQuestion
      summary: 知乎问题删除
      description: 知乎问题删除
      parameters:
        - name: id
          in: query
          type: string
          description: 问题编号
          required: true
      responses:
        '200':
          description: 请求访问结果
          schema:
            $ref: '#/definitions/ResultDTO'
        default:
          description: 返回错误信息
definitions:
  ResultDTO:
    type: object
    discriminator: ResultDTOType
    properties:
      result:
        type: string
        description: 返回编码
      errorMsg:
        type: string
        description: 返回错误信息

2>.接口定义图形化示例

3>.文档编写后，生成Spring代码

在该编辑页面选择【Generate Server】->【Spring】，生成的代码会自动下载。重点是接口Api。

//知乎问答API生成代码QuestionApi.java

import java.math.BigDecimal;
import io.swagger.model.InlineResponse200;

import io.swagger.annotations.*;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RequestPart;
import org.springframework.web.multipart.MultipartFile;

import java.util.List;
import javax.validation.constraints.*;
@javax.annotation.Generated(value = "io.swagger.codegen.languages.SpringCodegen", date = "2017-07-01T01:50:42.498Z")

@Api(value = "question", description = "the question API")
public interface QuestionApi {

    @ApiOperation(value = "知乎问题新增", notes = "知乎问题新增", response = InlineResponse200.class, tags={ "ZhihuQuestion", })
    @ApiResponses(value = { 
        @ApiResponse(code = 200, message = "应用服务器的应用信息列表", response = InlineResponse200.class),
        @ApiResponse(code = 200, message = "返回错误信息", response = InlineResponse200.class) })
    @RequestMapping(value = "/question/add",
        produces = { "application/json" }, 
        method = RequestMethod.POST)
    ResponseEntity<InlineResponse200> questionAddPost( @NotNull @ApiParam(value = "问题名称", required = true) @RequestParam(value = "question", required = true) String question,
         @NotNull @ApiParam(value = "问题提出者", required = true) @RequestParam(value = "author", required = true) String author,
         @NotNull @ApiParam(value = "问题url", required = true) @RequestParam(value = "url", required = true) String url,
         @ApiParam(value = "问题详情") @RequestParam(value = "questionDestion", required = false) String questionDestion);


    @ApiOperation(value = "知乎问题删除", notes = "知乎问题删除", response = InlineResponse200.class, tags={ "ZhihuQuestion", })
    @ApiResponses(value = { 
        @ApiResponse(code = 200, message = "请求访问结果", response = InlineResponse200.class),
        @ApiResponse(code = 200, message = "返回错误信息", response = InlineResponse200.class) })
    @RequestMapping(value = "/question/delete",
        produces = { "application/json" }, 
        method = RequestMethod.DELETE)
    ResponseEntity<InlineResponse200> questionDeleteDelete( @NotNull @ApiParam(value = "问题编号", required = true) @RequestParam(value = "id", required = true) String id);


    @ApiOperation(value = "知乎问题", notes = "知乎问题列表", response = InlineResponse200.class, tags={ "ZhihuQuestion", })
    @ApiResponses(value = { 
        @ApiResponse(code = 200, message = "应用服务器的应用信息列表", response = InlineResponse200.class),
        @ApiResponse(code = 200, message = "返回错误信息", response = InlineResponse200.class) })
    @RequestMapping(value = "/question/list",
        produces = { "application/json" }, 
        method = RequestMethod.GET)
    ResponseEntity<InlineResponse200> questionListGet( @NotNull @ApiParam(value = "起始页", required = true) @RequestParam(value = "start", required = true) BigDecimal start,
         @NotNull @ApiParam(value = "页展示数", required = true) @RequestParam(value = "size", required = true) BigDecimal size,
         @ApiParam(value = "过滤条件") @RequestParam(value = "filter", required = false) String filter);

}

//用户API生成代码UserApi.java

import java.math.BigDecimal;
import io.swagger.model.InlineResponse200;

import io.swagger.annotations.*;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RequestPart;
import org.springframework.web.multipart.MultipartFile;

import java.util.List;
import javax.validation.constraints.*;
@javax.annotation.Generated(value = "io.swagger.codegen.languages.SpringCodegen", date = "2017-07-01T01:50:42.498Z")

@Api(value = "user", description = "the user API")
public interface UserApi {

    @ApiOperation(value = "用户新增", notes = "用户新增", response = InlineResponse200.class, tags={ "ZhihuUser", })
    @ApiResponses(value = { 
        @ApiResponse(code = 200, message = "返回应用服务器的请求列表", response = InlineResponse200.class),
        @ApiResponse(code = 200, message = "返回错误信息", response = InlineResponse200.class) })
    @RequestMapping(value = "/user/add",
        produces = { "application/json" }, 
        method = RequestMethod.POST)
    ResponseEntity<InlineResponse200> userAddPost( @NotNull @ApiParam(value = "用户名", required = true) @RequestParam(value = "name", required = true) String name,
         @NotNull @ApiParam(value = "应用agentId", required = true) @RequestParam(value = "agentId", required = true) String agentId,
         @NotNull @ApiParam(value = "调用栈spanId", required = true) @RequestParam(value = "spanId", required = true) BigDecimal spanId,
         @ApiParam(value = "用户性别") @RequestParam(value = "sex", required = false) String sex);


    @ApiOperation(value = "用户删除", notes = "用户删除", response = InlineResponse200.class, tags={ "ZhihuUser", })
    @ApiResponses(value = { 
        @ApiResponse(code = 200, message = "返回应用服务器的请求列表", response = InlineResponse200.class),
        @ApiResponse(code = 200, message = "返回错误信息", response = InlineResponse200.class) })
    @RequestMapping(value = "/user/delete",
        produces = { "application/json" }, 
        method = RequestMethod.DELETE)
    ResponseEntity<InlineResponse200> userDeleteDelete( @NotNull @ApiParam(value = "用户id", required = true) @RequestParam(value = "id", required = true) String id);


    @ApiOperation(value = "用户修改", notes = "用户修改", response = InlineResponse200.class, tags={ "ZhihuUser", })
    @ApiResponses(value = { 
        @ApiResponse(code = 200, message = "返回应用服务器的请求列表", response = InlineResponse200.class),
        @ApiResponse(code = 200, message = "返回错误信息", response = InlineResponse200.class) })
    @RequestMapping(value = "/user/edit",
        produces = { "application/json" }, 
        method = RequestMethod.PUT)
    ResponseEntity<InlineResponse200> userEditPut( @NotNull @ApiParam(value = "用户id", required = true) @RequestParam(value = "id", required = true) String id,
         @NotNull @ApiParam(value = "用户名", required = true) @RequestParam(value = "name", required = true) String name,
         @NotNull @ApiParam(value = "应用agentId", required = true) @RequestParam(value = "agentId", required = true) String agentId,
         @NotNull @ApiParam(value = "调用栈spanId", required = true) @RequestParam(value = "spanId", required = true) BigDecimal spanId,
         @ApiParam(value = "用户性别") @RequestParam(value = "sex", required = false) String sex);


    @ApiOperation(value = "用户展示", notes = "知乎用户列表", response = InlineResponse200.class, tags={ "ZhihuUser", })
    @ApiResponses(value = { 
        @ApiResponse(code = 200, message = "返回应用服务器的请求列表", response = InlineResponse200.class),
        @ApiResponse(code = 200, message = "返回错误信息", response = InlineResponse200.class) })
    @RequestMapping(value = "/user/list",
        produces = { "application/json" }, 
        method = RequestMethod.GET)
    ResponseEntity<InlineResponse200> userListGet( @NotNull @ApiParam(value = "起始页", required = true) @RequestParam(value = "start", required = true) BigDecimal start,
         @NotNull @ApiParam(value = "页展示数", required = true) @RequestParam(value = "size", required = true) BigDecimal size,
         @ApiParam(value = "过滤条件") @RequestParam(value = "filter", required = false) String filter);

}

4.设定访问API doc的路由

在配置文件中，application.yml中声明：

#这个path就是json的访问request mapping.可以自定义，防止与自身代码冲突。

springfox：
  documentation:
    swagger:
      v2:
        path: /api-docs

#API doc的显示路由是：http://localhost:8080/swagger-ui.html        

如果项目是一个webservice，通常设定home / 指向这里：

@Controller
public class HomeController {

    @RequestMapping(value = "/swagger")
    public String index() {
        System.out.println("swagger-ui.html");
        return "redirect:swagger-ui.html";
    }
}

5.项目的开源地址

https://github.com/sdc1234/zhihu-spider