aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorRigel Kent <sendmemail@rigelk.eu>2020-02-18 14:49:11 +0100
committerRigel Kent <sendmemail@rigelk.eu>2020-02-18 14:49:11 +0100
commitd5edf22aadfb6a18268c5eb6e172c7bef55e240c (patch)
treea5221fd1a246122ff95182c9dc1d1fb115dfd483
parent71e75ef27e8f993eaafc73896ac6f22fe91df64a (diff)
parent170cd639a7ed591184fde23968b2d24dac630e45 (diff)
downloadPeerTube-d5edf22aadfb6a18268c5eb6e172c7bef55e240c.tar.gz
PeerTube-d5edf22aadfb6a18268c5eb6e172c7bef55e240c.tar.zst
PeerTube-d5edf22aadfb6a18268c5eb6e172c7bef55e240c.zip
Merge branch 'feature/better-openapi-readmes' into 'develop'
See merge request framasoft/peertube/PeerTube!29
-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