yaml,openApi、服务开发流程

summary_2018/06 standard think

1、日常工作

1、使用openApi规范完成facebook_insight_status service 的编写，及重构
2、openApi规范学习
3、YAML（一种通用的数据串行化格式）
4、服务开发流程

2、技术学习

1、openApi规范学习

• The complete OpenAPI Specification
• OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. . An OpenAPI file allows you to describe your entire API, including:
  
  • Available endpoints (/users) and operations on each endpoint (GET /users, POST /users)
  • Operation parameters Input and output for each operation
  • Authentication methods
  • Contact information, license, terms of use and other information.
• 在线编辑器
• 内容比较丰富，我只提几个比较常用的字段：
  
  • You can write OpenAPI definitions in YAML or JSON. In this guide, we use only YAML examples。
  • Parameters
  • Request Body
  • Responses

#### Metadata
//每个OpenAPI规范都以openapi提到规范格式版本的关键字开始。该版本定义了API规范的整体结构 - 您可以记录什么以及如何记录它。
openapi: 3.0.0
//info部分包含API信息：title，description（可选）version
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9
#### Servers
//The servers section specifies the API server and base URL. You can define one or several servers, such as production and sandbox.
servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing
#### Paths
The paths section defines individual endpoints (paths) in your API, and the HTTP methods (operations) supported by these endpoints.
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML
#### Parameters
parameters:
- name: petId
  in: path
  description: ID of pet that needs to be updated
  required: true
  schema:
    type: string
#### Request Body
requestBody:
  content:
    application/octet-stream:
      # any media type is accepted, functionally equivalent to `*/*`
      schema:
        # a binary file of any type
        type: string
        format: binary
#### Responses
paths:
  /user/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - name: userId
          in: path
          required: true
          description: The ID of the user to return.
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        '200':
          description: A user object.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                    example: 4
                  name:
                    type: string
                    example: Jessica Smith
        '400':
          description: The specified user ID is invalid (not a number).
        '404':
          description: A user with the specified ID was not found.
        default:
          description: Unexpected error
Example:
openapi: 3.0.0
info:
  title: 'xxx'
  description: 'xxx'
  version: "1.0.0"
tags:
- name: 'adInsightAndAction'
  description: 'xxx'
paths:
  /insights:
    get:
      tags:
      - 'adInsightAndAction'
      description: ''
      operationId: 'getAdInsightAndAction'
      parameters:
      - in: 'query'
        name: 'access_token'
        schema:
          type: 'string'
        example: 'xxxxxx'
        description: 'xxx'
        required: true
      - in: 'query'
        name: 'ids'
        schema:
          type: 'string'
        example: '<id1>,<id2>....'
        description: 'ids of you need query'
        required: true
      responses:
        200:
          description:  |
            - level:
              - 50 : id not exist or other error
              - 30 : get data successfully
          content:
            application/json:
              schema:
                type: 'array'
                items:
                  type: 'object'
                  properties:
                    level:
                      type: 'integer'
                      example: 30
                    message:
                      type: 'object'
                      properties:
                        ad_id:
                          type: 'string'
                          example: '23842921610'
                        spend:
                          type: 'string'
                          example: '287.29'
                        action:
                          type: 'array'
                          items:
                            type: 'object'
                            properties:
                              action_type:
                                type: 'string'
                                example: 'app_custom_event.fb_mobile'
                              value:
                                type: 'string'
                                example: '251'
                        date_start:
                          type: 'string'
                          example: '2018-05-22'
                        date_stop:
                          type: 'string'
                          example: '2018-05-22'

• 2、服务开发流程

  • 理解需求
  • 初始化项目，创建主分支，在研发分支进行开发
  • 设计接口（草案）
  • 研发项目（对部分功能提供单元测试）
  • 编写接口测试，尽量提高覆盖率
  • 编写readme.md(introduction+usage(api可单独分开)+test(env))
  • 通过代码检查
  • 推送到研发分支，发起MR，进行codereviw(一定要自己先review)
  • 合并到主分支，投入使用

• 3、思考总结

  • 在实际项目中需注意细节（比如一些写法,用意清晰），避免小问题重复返工
  • 注意整个开发流程的步骤，提高效率及团队合作