API和REST

API：应用程序编程接口，例如：可以用手机的其他软件分享内容到微信朋友圈或者新浪微博，这些软件就是与微信和微博的api进行了交互。

REST：是一种架构规则，腾讯公司或其他公司建立API时要遵守的一种规则/风格。

Swagger的用处

Swagger是一个Rest Apis文档生成工具，通过swagger我们可以使用JSON或者YAML来描述自己的API（可以使用swagger editor来编写验证YAML文件）；在编写好api的yaml文件后，前端可以在swagger ui中查看每个api的输入与输出，后端可以通过swagger-codegen工具来生成对应的api框架代码；通过这种方式来实现前后端分离开发。

如果你是服务端开发人员，也许你要做以下工作：
1、写接口文档，描述每个接口的功能，请求参数和返回结果
2、生成API文档、并进行手动的测试

使用swagger-ui开源工具，建立一个API的集设计，实现，测试，文档的一体化可视平台，让API的开发和使用更加高效

优势：
Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
Swagger 文档提供了一个方法，使我们可以用指定的 JSON 或者 YAML 摘要来描述API，包括了比如 names、order 等 API 信息。

Swagger的框架

Swagger Editor – browser-based editor where you can write OpenAPI specs.
Swagger UI – renders OpenAPI specs as interactive API documentation.
Swagger Codegen – generates server stubs and client libraries from an OpenAPI spec

操作一：搭建计费系统的环境

实验项目1：
在docker中存放redis数据库，计费系统的go项目放在本机MAC上，通过端口在本机MAC上对容器内的PostgreS数据库进行post、get、delete、put（使用python脚本）。

重点：使用什么端口来通信理解起来有点复杂，花费了我一些时间，先上图：

image.png

3）在MAC中安装go语言
网上太多，不做陈述，注意GOPATH环境的配置，计费系统的源代码scr存放的位置要在配置的环境下：/usr/local/go/src/peont（这是我的项目存放位置）。通过go run运行main.go 文件

4）写python脚本进行手工录入验证，看到已经成功录入

#!/usr/bin/env python
#coding=utf8
import requests,json,time
github_url="http://127.0.0.1:4000/consuming/v1/cost"
data=json.dumps({
    'UserId':'1112',
    'PriceId':'2222',
    'ResourceType':'cpu',
    'StartTime':None,
    'EndTime':None,
    'BillingCost':2.5})
r=requests.post(github_url,data)
print r.text

image.png

操作二：写Swagger API文档

#OpenAPI 的规范
openapi: 3.0.0  

# info section contains API information: title, description (optional), version
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9

#API server and base URL，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

#defines individual endpoints (paths) in your API
#An operation definition includes parameters, request body (if any), possible response status codes (such as 200 OK or 404 Not Found) and response contents.
paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
#Operations can have parameters passed via URL path (/users/{userId}), query string (/users?role=admin), headers (X-CustomHeader: Value) or cookies (Cookie: debug=0). You can define the parameter data types, format, whether they are required or optional, and other detail

      requestBody:
        required: true
        content:
          'application/json':
            schema:
              type: object
              properties:
                username:
                  type: string
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            'application/json':
              schema: 
                type: array
                items: 
                  type: string

file:///Users/fanfan/Desktop/cloud_intern/swagger/swagger-editor-master/index.html

develop a RESTful API testbed using Swagger
https://scotch.io/tutorials/document-your-already-existing-apis-with-swagger