aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorAverage Dude <loveisgrief@tuta.io>2020-02-18 14:49:11 +0100
committerRigel Kent <sendmemail@rigelk.eu>2020-02-18 14:49:11 +0100
commit170cd639a7ed591184fde23968b2d24dac630e45 (patch)
treea5221fd1a246122ff95182c9dc1d1fb115dfd483
parent71e75ef27e8f993eaafc73896ac6f22fe91df64a (diff)
downloadPeerTube-170cd639a7ed591184fde23968b2d24dac630e45.tar.gz
PeerTube-170cd639a7ed591184fde23968b2d24dac630e45.tar.zst
PeerTube-170cd639a7ed591184fde23968b2d24dac630e45.zip
Create template dirs for openapi clients and provide README templates
The definitions are now also in the template dirs because they will be ignored by the generator. Generators only use overrides and don't do anything with new files.
-rwxr-xr-xscripts/openapi-clients.sh5
-rw-r--r--support/openapi/go/README.mustache121
-rw-r--r--support/openapi/go/def.yaml (renamed from support/openapi/go.yaml)0
-rw-r--r--support/openapi/kotlin/README.mustache97
-rw-r--r--support/openapi/kotlin/def.yaml (renamed from support/openapi/kotlin.yaml)0
-rw-r--r--support/openapi/python/README.mustache47
-rw-r--r--support/openapi/python/def.yaml (renamed from support/openapi/python.yaml)0
7 files changed, 269 insertions, 1 deletions
diff --git a/scripts/openapi-clients.sh b/scripts/openapi-clients.sh
index b031ceac1..c799658e3 100755
--- a/scripts/openapi-clients.sh
+++ b/scripts/openapi-clients.sh
@@ -46,6 +46,8 @@ for lang in ${API_LANGS//:/ } ; do
46( 46(
47 echo "Generating client API libs for $lang" 47 echo "Generating client API libs for $lang"
48 48
49 lang_dir="support/openapi/${lang}"
50
49 out_dir_prefix="dist/api/${API_PATH_PREFIX}" 51 out_dir_prefix="dist/api/${API_PATH_PREFIX}"
50 out_dir="${out_dir_prefix}/${lang}" 52 out_dir="${out_dir_prefix}/${lang}"
51 git_repo_id="${API_PATH_PREFIX}${lang}" 53 git_repo_id="${API_PATH_PREFIX}${lang}"
@@ -59,7 +61,8 @@ for lang in ${API_LANGS//:/ } ; do
59 61
60 npx openapi-generator generate \ 62 npx openapi-generator generate \
61 -i support/doc/api/openapi.yaml \ 63 -i support/doc/api/openapi.yaml \
62 -c "support/openapi/${lang}.yaml" \ 64 -c "${lang_dir}/def.yaml" \
65 -t "${lang_dir}" \
63 -g "$lang" \ 66 -g "$lang" \
64 --git-host "${API_REPO_HOST}" \ 67 --git-host "${API_REPO_HOST}" \
65 --git-user-id "${API_URL_USERNAME}" \ 68 --git-user-id "${API_URL_USERNAME}" \
diff --git a/support/openapi/go/README.mustache b/support/openapi/go/README.mustache
new file mode 100644
index 000000000..d0fc0fa33
--- /dev/null
+++ b/support/openapi/go/README.mustache
@@ -0,0 +1,121 @@
1# Go API client for {{appName}}
2
3This Python package is automatically generated from [PeerTube's REST API](https://docs.joinpeertube.org/api-rest-reference.html),
4using the [OpenAPI Generator](https://openapi-generator.tech) project:
5
6- API version: {{appVersion}}
7- Package version: {{packageVersion}}
8{{^hideGenerationTimestamp}}
9- Build date: {{generatedDate}}
10{{/hideGenerationTimestamp}}
11- Build package: {{generatorClass}}
12
13{{#infoUrl}}
14For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
15{{/infoUrl}}
16
17## Installation
18
19Install the following dependencies:
20
21```shell
22go get github.com/stretchr/testify/assert
23go get golang.org/x/oauth2
24go get golang.org/x/net/context
25go get github.com/antihax/optional
26```
27
28Put the package under your project folder and add the following in import:
29
30```golang
31import "./{{packageName}}"
32```
33
34## Documentation for API Endpoints
35
36All URIs are relative to *{{basePath}}*
37
38Class | Method | HTTP request | Description
39------------ | ------------- | ------------- | -------------
40{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
41{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
42
43## Documentation For Models
44
45{{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
46{{/model}}{{/models}}
47
48## Documentation For Authorization
49
50{{^authMethods}} Endpoints do not require authorization.
51{{/authMethods}}{{#authMethods}}{{#last}} Authentication schemes defined for the API:{{/last}}{{/authMethods}}
52{{#authMethods}}
53
54## {{{name}}}
55
56{{#isApiKey}}- **Type**: API key
57
58Example
59
60```golang
61auth := context.WithValue(context.Background(), sw.ContextAPIKey, sw.APIKey{
62 Key: "APIKEY",
63 Prefix: "Bearer", // Omit if not necessary.
64})
65r, err := client.Service.Operation(auth, args)
66```
67
68{{/isApiKey}}
69{{#isBasic}}- **Type**: HTTP basic authentication
70
71Example
72
73```golang
74auth := context.WithValue(context.Background(), sw.ContextBasicAuth, sw.BasicAuth{
75 UserName: "username",
76 Password: "password",
77})
78r, err := client.Service.Operation(auth, args)
79```
80
81{{/isBasic}}
82{{#isOAuth}}
83
84- **Type**: OAuth
85- **Flow**: {{{flow}}}
86- **Authorization URL**: {{{authorizationUrl}}}
87- **Scopes**: {{^scopes}}N/A{{/scopes}}
88{{#scopes}} - **{{{scope}}}**: {{{description}}}
89{{/scopes}}
90
91Example
92
93```golang
94auth := context.WithValue(context.Background(), sw.ContextAccessToken, "ACCESSTOKENSTRING")
95r, err := client.Service.Operation(auth, args)
96```
97
98Or via OAuth2 module to automatically refresh tokens and perform user authentication.
99
100```golang
101import "golang.org/x/oauth2"
102
103/* Perform OAuth2 round trip request and obtain a token */
104
105tokenSource := oauth2cfg.TokenSource(createContext(httpClient), &token)
106auth := context.WithValue(oauth2.NoContext, sw.ContextOAuth2, tokenSource)
107r, err := client.Service.Operation(auth, args)
108```
109
110{{/isOAuth}}
111{{/authMethods}}
112
113## License
114
115Copyright (C) 2015-2020 PeerTube Contributors
116
117This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
118
119This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
120
121You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses.
diff --git a/support/openapi/go.yaml b/support/openapi/go/def.yaml
index 7136da912..7136da912 100644
--- a/support/openapi/go.yaml
+++ b/support/openapi/go/def.yaml
diff --git a/support/openapi/kotlin/README.mustache b/support/openapi/kotlin/README.mustache
new file mode 100644
index 000000000..ac7fbdea9
--- /dev/null
+++ b/support/openapi/kotlin/README.mustache
@@ -0,0 +1,97 @@
1# Kotlin API client for {{appName}}
2
3## Requires
4
5{{#jvm}}
6* Kotlin 1.3.41
7* Gradle 4.9
8{{/jvm}}
9{{#multiplatform}}
10* Kotlin 1.3.50
11{{/multiplatform}}
12
13## Build
14
15{{#jvm}}
16First, create the gradle wrapper script:
17
18```
19gradle wrapper
20```
21
22Then, run:
23
24{{/jvm}}
25```
26./gradlew check assemble
27```
28
29This runs all tests and packages the library.
30
31## Features/Implementation Notes
32
33{{#generateApiDocs}}
34<a name="documentation-for-api-endpoints"></a>
35## Documentation for API Endpoints
36
37All URIs are relative to *{{{basePath}}}*. Change it when instanciating `ApiClient(basePath)`.
38
39Class | Method | HTTP request | Description
40------------ | ------------- | ------------- | -------------
41{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{{summary}}}{{/summary}}
42{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
43{{/generateApiDocs}}
44
45{{#generateModelDocs}}
46<a name="documentation-for-models"></a>
47## Documentation for Models
48
49{{#modelPackage}}
50{{#models}}{{#model}} - [{{{modelPackage}}}.{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
51{{/model}}{{/models}}
52{{/modelPackage}}
53{{^modelPackage}}
54No model defined in this package
55{{/modelPackage}}
56{{/generateModelDocs}}
57
58<a name="documentation-for-authorization"></a>{{! TODO: optional documentation for authorization? }}
59## Documentation for Authorization
60
61{{^authMethods}}
62All endpoints do not require authorization.
63{{/authMethods}}
64{{#authMethods}}
65{{#last}}
66Authentication schemes defined for the API:
67{{/last}}
68{{/authMethods}}
69{{#authMethods}}
70<a name="{{name}}"></a>
71### {{name}}
72
73{{#isApiKey}}- **Type**: API key
74- **API key parameter name**: {{keyParamName}}
75- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
76{{/isApiKey}}
77{{#isBasic}}- **Type**: HTTP basic authentication
78{{/isBasic}}
79{{#isOAuth}}- **Type**: OAuth
80- **Flow**: {{flow}}
81- **Authorization URL**: {{authorizationUrl}}
82- **Scopes**: {{^scopes}}N/A{{/scopes}}
83{{#scopes}} - {{scope}}: {{description}}
84{{/scopes}}
85{{/isOAuth}}
86
87{{/authMethods}}
88
89## License
90
91Copyright (C) 2015-2020 PeerTube Contributors
92
93This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
94
95This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
96
97You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses.
diff --git a/support/openapi/kotlin.yaml b/support/openapi/kotlin/def.yaml
index 7a01ae6e5..7a01ae6e5 100644
--- a/support/openapi/kotlin.yaml
+++ b/support/openapi/kotlin/def.yaml
diff --git a/support/openapi/python/README.mustache b/support/openapi/python/README.mustache
new file mode 100644
index 000000000..93dcd5ab6
--- /dev/null
+++ b/support/openapi/python/README.mustache
@@ -0,0 +1,47 @@
1# Python API client for {{appName}}
2
3This Python package is automatically generated from [PeerTube's REST API](https://docs.joinpeertube.org/api-rest-reference.html),
4using the [OpenAPI Generator](https://openapi-generator.tech) project:
5
6- API version: {{appVersion}}
7- Package version: {{packageVersion}}
8{{^hideGenerationTimestamp}}
9- Build date: {{generatedDate}}
10{{/hideGenerationTimestamp}}
11- Build package: {{generatorClass}}
12
13{{#infoUrl}}
14For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
15{{/infoUrl}}
16
17## Requirements.
18
19Python 2.7 and 3.4+
20
21## Installation & Usage
22
23```sh
24pip install git+https://{{gitHost}}/{{{gitUserId}}}/{{{gitRepoId}}}.git
25```
26(you may need to run `pip` with root permission: `sudo pip install git+https://{{gitHost}}/{{{gitUserId}}}/{{{gitRepoId}}}.git`)
27
28Then import the package:
29```python
30import {{{packageName}}}
31```
32
33## Getting Started
34
35Please follow the [installation procedure](#installation--usage) and then run the following:
36
37{{> common_README }}
38
39## License
40
41Copyright (C) 2015-2020 PeerTube Contributors
42
43This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
44
45This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
46
47You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses.
diff --git a/support/openapi/python.yaml b/support/openapi/python/def.yaml
index 819a466eb..819a466eb 100644
--- a/support/openapi/python.yaml
+++ b/support/openapi/python/def.yaml