1 | # open-api
|
2 | [![Build Status][travis-img]][travis]
|
3 | [![Build status][av-img]][av]
|
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 | [![screenshot of netlify swagger ui](ui/screenshot.png)](https://open-api.netlify.com)
|
20 |
|
21 | ### Go Client
|
22 |
|
23 | [![GoDoc][godoc-img]][godoc]
|
24 | [![Go Report Card][goreport-img]][goreport]
|
25 | [![Github release][git-img]][git]
|
26 |
|
27 | ```console
|
28 | $ go get github.com/netlify/open-api/...
|
29 | ```
|
30 |
|
31 | - [Porcelain](https://godoc.org/github.com/netlify/open-api/go/porcelain): High level interactions and operations
|
32 | - [Plumbing](https://godoc.org/github.com/netlify/open-api/go/plumbing): Low level client operations generated by [go-swagger][go-swagger]
|
33 | - [Models](https://godoc.org/github.com/netlify/open-api/go/porcelain): Models generated by [go-swagger][go-swagger]
|
34 |
|
35 | See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how this client is developed and generated.
|
36 |
|
37 | ### JS Client
|
38 |
|
39 | [![npm version][npm-js-img]][npm-js] [![downloads][dl-js-img]][dl-js]
|
40 |
|
41 | 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.
|
42 |
|
43 | See [github.com/netlify/js-client](https://github.com/netlify/js-client) for more details.
|
44 |
|
45 | #### npm module
|
46 |
|
47 | [![npm version][npm-img]][npm]
|
48 |
|
49 | You can also consume the swagger spec as an npm module:
|
50 |
|
51 | ```console
|
52 | $ npm install @netlify/open-api
|
53 | # or
|
54 | $ yarn add @netlify/open-api
|
55 | ```
|
56 |
|
57 | ```js
|
58 | import spec from '@netlify/open-api' // import the spec object into your project
|
59 | ```
|
60 |
|
61 | 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:
|
62 |
|
63 | ##### swagger-js
|
64 |
|
65 | Swagger's JS client can dynamically create a client from a spec either from a URL or spec object.
|
66 |
|
67 | See the [swagger-js](https://github.com/swagger-api/swagger-js) client:
|
68 |
|
69 | ##### Usage
|
70 | ```js
|
71 | <script src='browser/swagger-client.js' type='text/javascript'></script>
|
72 | <script>
|
73 | var swaggerClient = new SwaggerClient('https://open-api.netlify.com/swagger.json');
|
74 | </script>
|
75 | ```
|
76 |
|
77 | ## Contributing
|
78 |
|
79 | See [CONTRIBUTING.md](CONTRIBUTING.md) for more info on how to make contributions to this project.
|
80 |
|
81 | ## License
|
82 |
|
83 | MIT. See [LICENSE](LICENSE) for more details.
|
84 |
|
85 | [travis-img]: https://travis-ci.org/netlify/open-api.svg?branch=master
|
86 | [travis]: https://travis-ci.org/netlify/open-api
|
87 | [av]: https://ci.appveyor.com/project/netlify/open-api/branch/master
|
88 | [av-img]: https://ci.appveyor.com/api/projects/status/1g0m72jqhspar6q9/branch/master?svg=true
|
89 | [npm-img]: https://img.shields.io/npm/v/@netlify/open-api.svg
|
90 | [npm]: https://npmjs.org/package/@netlify/open-api
|
91 | [npm-js-img]: https://img.shields.io/npm/v/netlify.svg
|
92 | [npm-js]: https://npmjs.org/package/netlify
|
93 | [dl-js-img]: https://img.shields.io/npm/dm/netlify.svg
|
94 | [dl-js]: https://npmjs.org/package/netlify
|
95 |
|
96 | [godoc-img]: https://godoc.org/github.com/netlify/open-api/go?status.svg
|
97 | [godoc]: https://godoc.org/github.com/netlify/open-api/go
|
98 | [goreport-img]: https://goreportcard.com/badge/github.com/netlify/open-api
|
99 | [goreport]: https://goreportcard.com/report/github.com/netlify/open-api
|
100 | [git-img]: https://img.shields.io/github/release/netlify/open-api.svg
|
101 | [git]: https://github.com/netlify/open-api/releases/latest
|
102 |
|
103 | [open-api-2]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
|
104 | [go-swagger]: https://github.com/go-swagger/go-swagger
|