1 | ![open-api](api.png)
|
2 |
|
3 | [![Build Status][travis-img]][travis]
|
4 |
|
5 | This repository contains Netlify's API definition in the [Open API format][open-api-2], formerly known as Swagger.
|
6 |
|
7 | It's still a work in progress and we welcome feedback and contributions.
|
8 |
|
9 | ## Usage
|
10 |
|
11 | The [`swagger.yml`](swagger.yml) file is the master copy of the Open API 2.0 definition. Additional context on using the API can be found on our [docs site](https://www.netlify.com/docs/api/).
|
12 |
|
13 | The spec is published and versioned for various ecosystems:
|
14 |
|
15 | ### SwaggerUI (Web UI)
|
16 |
|
17 | You can view the definition using [Swagger UI](https://swagger.io/tools/swagger-ui/) by visiting [open-api.netlify.com](http://open-api.netlify.com) which provides limited interaction with the API from the browser.
|
18 |
|
19 | ### Go Client
|
20 |
|
21 | [![GoDoc][godoc-img]][godoc]
|
22 | [![Go Report Card][goreport-img]][goreport]
|
23 | [![Github release][git-img]][git]
|
24 |
|
25 | ```console
|
26 | $ go get github.com/netlify/open-api/...
|
27 | ```
|
28 |
|
29 | - [Porcelain](https://godoc.org/github.com/netlify/open-api/v2/go/porcelain): High level interactions and operations
|
30 | - [Plumbing](https://godoc.org/github.com/netlify/open-api/v2/go/plumbing): Low level client operations generated by [go-swagger][go-swagger]
|
31 | - [Models](https://godoc.org/github.com/netlify/open-api/v2/go/models): Models generated by [go-swagger][go-swagger]
|
32 |
|
33 | See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how this client is developed and generated.
|
34 |
|
35 | ### JS Client
|
36 |
|
37 | [![npm version][npm-js-img]][npm-js] [![downloads][dl-js-img]][dl-js]
|
38 |
|
39 | We have a fully featured JS/Node.js client that implements some of the same 'porcelain' methods that the go client does in addition to the open-api methods.
|
40 |
|
41 | See [github.com/netlify/js-client](https://github.com/netlify/js-client) for more details.
|
42 |
|
43 | #### npm module
|
44 |
|
45 | [![npm version][npm-img]][npm]
|
46 |
|
47 | You can also consume the swagger spec as an npm module:
|
48 |
|
49 | ```console
|
50 | $ npm install @netlify/open-api
|
51 | # or
|
52 | $ yarn add @netlify/open-api
|
53 | ```
|
54 |
|
55 | ```js
|
56 | import spec from '@netlify/open-api' // import the spec object into your project
|
57 | ```
|
58 |
|
59 | The module also ships a copy of the original `yml` spec file at `@netlify/open-api/js/dist/swagger.yml`. You can use these with generic swagger/open-api clients:
|
60 |
|
61 | ##### swagger-js
|
62 |
|
63 | Swagger's JS client can dynamically create a client from a spec either from a URL or spec object.
|
64 |
|
65 | See the [swagger-js](https://github.com/swagger-api/swagger-js) client:
|
66 |
|
67 | ##### Usage
|
68 |
|
69 | ```js
|
70 | <script src='browser/swagger-client.js' type='text/javascript'></script>
|
71 | <script>
|
72 | var swaggerClient = new SwaggerClient('https://open-api.netlify.com/swagger.json');
|
73 | </script>
|
74 | ```
|
75 |
|
76 | ## Contributing
|
77 |
|
78 | See [CONTRIBUTING.md](CONTRIBUTING.md) for more info on how to make contributions to this project.
|
79 |
|
80 | ## License
|
81 |
|
82 | MIT. See [LICENSE](LICENSE) for more details.
|
83 |
|
84 | [travis-img]: https://travis-ci.org/netlify/open-api.svg?branch=master
|
85 | [travis]: https://travis-ci.org/netlify/open-api
|
86 | [npm-img]: https://img.shields.io/npm/v/@netlify/open-api.svg
|
87 | [npm]: https://npmjs.org/package/@netlify/open-api
|
88 | [npm-js-img]: https://img.shields.io/npm/v/netlify.svg
|
89 | [npm-js]: https://npmjs.org/package/netlify
|
90 | [dl-js-img]: https://img.shields.io/npm/dm/netlify.svg
|
91 | [dl-js]: https://npmjs.org/package/netlify
|
92 | [godoc-img]: https://godoc.org/github.com/netlify/open-api/v2/go?status.svg
|
93 | [godoc]: https://godoc.org/github.com/netlify/open-api/v2/go
|
94 | [goreport-img]: https://goreportcard.com/badge/github.com/netlify/open-api/v2
|
95 | [goreport]: https://goreportcard.com/report/github.com/netlify/open-api/v2
|
96 | [git-img]: https://img.shields.io/github/release/netlify/open-api.svg
|
97 | [git]: https://github.com/netlify/open-api/releases/latest
|
98 | [open-api-2]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
|
99 | [go-swagger]: https://github.com/go-swagger/go-swagger
|