Skip to content

Latest commit

 

History

History
148 lines (100 loc) · 6.56 KB

README.md

File metadata and controls

148 lines (100 loc) · 6.56 KB
Raw

Wechaty Puppet OpenAPI Specification (OAS)

Wechaty REST API Server with OpenAPI Specification (Swagger)

Table of Contents
  1. About
  2. Motivation
  3. Screenshots
  4. Features
  5. Install
  6. Usage
  7. Architecture
  8. Resources
  9. Contributing
  10. Author
  11. Copyright & License

About

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.

API specifications can be written in YAML or JSON. The format is easy to learn and readable to both humans and machines. The complete OpenAPI Specification can be found on GitHub: OpenAPI 3.0 Specification

NOTE:

This repo is working in the process. We hope we can finish an alpha version in April, and be ready to Beta in May!

Issues & PRs are welcome, thank you very much for your attention.

Motivation

We have OpenAPI for Wechaty Puppet, and we want a RESTful API as well, so we built OpenAPI Specification (OAS, former Swagger) on top of gRPC, with the power of gRPC OAS Gateway.

Screenshots


View Wechaty OpenAPI Specification on SwaggerHub

Features

  1. A Standalone HTTP Server wechaty-openapi-server
  2. An Express Router for easy mounting to any existing Express HTTP Server.

Install

npm install wechaty-openapi

Usage

1. Standalone Server

export WECHATY_PUPPET_SERVICE_TOKEN=__YOUR_TOKEN__
wechaty-openapi-server \
  --mountpoint /api
  --port 8080

Then visit http://localhost:8080/api

2. Express Router

TBW

Architecture

Thanks to the ecosystem of gRPC, we can generate OpenAPI Specification from our gRPC proto definitions automatically.

We are using gRPC to JSON proxy generator following the gRPC HTTP spec as the OpenAPI Specification generator (protoc-gen-openapiv2), and using Like grpc-gateway, but written in node and dynamic project to serve an HTTP RESTful API to gRPC proxy.

Image credit: gRPC Gateway

Learn more about the RESTful API service for Wechaty from Wechaty OpenAPI.

See also: AIP-4222 - Routing headers

Resources

Read blogs with the openapi tag at https://wechaty.js.org/tags.html#openapi.

Check out RESOURCES.md file for learning resources.

Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

See CONTRIBUTING.md for more details.

Releases

Since its creation in 2016, a number of Wechaty versions have been released. For more information about the release history and the current stable version, you can read the Wechaty release notes on Github.

Maintainer

Wechaty is maintained by Huan, Rui, and a community of Open Source Contributors. We are always looking for people to join the Wechaty community to maintain the Wechaty codebase and documentation. You necessarily don't have to be a programmer to contribute to Wechaty. To get started contributing, you can read the CONTRIBUTING.md.

Getting help

Wechaty has a community of very helpful contributors on different platforms you can join to get help from. Before joining any of the communities, we recommend that you read our Code of conduct]o that you adhere to our community guidelines. A full list of the different Wechaty communities can be accessed from the Wechaty community section of this documentation.

Copyright & License

Wechaty is an Open Source Project. It is released under Apache-2.0 license and the corresponding documentation is released under the Creative Commons license.