Merge branch 'feature/better-openapi-readmes' into 'develop'

See merge request framasoft/peertube/PeerTube!29

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
 (
     echo "Generating client API libs for $lang"
 
+    lang_dir="support/openapi/${lang}"
+
     out_dir_prefix="dist/api/${API_PATH_PREFIX}"
     out_dir="${out_dir_prefix}/${lang}"
     git_repo_id="${API_PATH_PREFIX}${lang}"
@@ -59,7 +61,8 @@ for lang in ${API_LANGS//:/ } ; do
 
     npx openapi-generator generate \
         -i support/doc/api/openapi.yaml \
-        -c "support/openapi/${lang}.yaml" \
+        -c "${lang_dir}/def.yaml" \
+        -t "${lang_dir}" \
         -g "$lang" \
         --git-host "${API_REPO_HOST}" \
         --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 @@
+# Go API client for {{appName}}
+
+This Python package is automatically generated from [PeerTube's REST API](https://docs.joinpeertube.org/api-rest-reference.html),
+using the [OpenAPI Generator](https://openapi-generator.tech) project:
+
+- API version: {{appVersion}}
+- Package version: {{packageVersion}}
+{{^hideGenerationTimestamp}}
+- Build date: {{generatedDate}}
+{{/hideGenerationTimestamp}}
+- Build package: {{generatorClass}}
+
+{{#infoUrl}}
+For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
+{{/infoUrl}}
+
+## Installation
+
+Install the following dependencies:
+
+```shell
+go get github.com/stretchr/testify/assert
+go get golang.org/x/oauth2
+go get golang.org/x/net/context
+go get github.com/antihax/optional
+```
+
+Put the package under your project folder and add the following in import:
+
+```golang
+import "./{{packageName}}"
+```
+
+## Documentation for API Endpoints
+
+All URIs are relative to *{{basePath}}*
+
+Class | Method | HTTP request | Description
+------------ | ------------- | ------------- | -------------
+{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{summary}}{{/summary}}
+{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
+
+## Documentation For Models
+
+{{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
+{{/model}}{{/models}}
+
+## Documentation For Authorization
+
+{{^authMethods}} Endpoints do not require authorization.
+{{/authMethods}}{{#authMethods}}{{#last}} Authentication schemes defined for the API:{{/last}}{{/authMethods}}
+{{#authMethods}}
+
+## {{{name}}}
+
+{{#isApiKey}}- **Type**: API key
+
+Example
+
+```golang
+auth := context.WithValue(context.Background(), sw.ContextAPIKey, sw.APIKey{
+    Key: "APIKEY",
+    Prefix: "Bearer", // Omit if not necessary.
+})
+r, err := client.Service.Operation(auth, args)
+```
+
+{{/isApiKey}}
+{{#isBasic}}- **Type**: HTTP basic authentication
+
+Example
+
+```golang
+auth := context.WithValue(context.Background(), sw.ContextBasicAuth, sw.BasicAuth{
+    UserName: "username",
+    Password: "password",
+})
+r, err := client.Service.Operation(auth, args)
+```
+
+{{/isBasic}}
+{{#isOAuth}}
+
+- **Type**: OAuth
+- **Flow**: {{{flow}}}
+- **Authorization URL**: {{{authorizationUrl}}}
+- **Scopes**: {{^scopes}}N/A{{/scopes}}
+{{#scopes}} - **{{{scope}}}**: {{{description}}}
+{{/scopes}}
+
+Example
+
+```golang
+auth := context.WithValue(context.Background(), sw.ContextAccessToken, "ACCESSTOKENSTRING")
+r, err := client.Service.Operation(auth, args)
+```
+
+Or via OAuth2 module to automatically refresh tokens and perform user authentication.
+
+```golang
+import "golang.org/x/oauth2"
+
+/* Perform OAuth2 round trip request and obtain a token */
+
+tokenSource := oauth2cfg.TokenSource(createContext(httpClient), &token)
+auth := context.WithValue(oauth2.NoContext, sw.ContextOAuth2, tokenSource)
+r, err := client.Service.Operation(auth, args)
+```
+
+{{/isOAuth}}
+{{/authMethods}}
+
+## License
+
+Copyright (C) 2015-2020 PeerTube Contributors
+
+This 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.
+
+This 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.
+
+You 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 @@
+# Kotlin API client for {{appName}}
+
+## Requires
+
+{{#jvm}}
+* Kotlin 1.3.41
+* Gradle 4.9
+{{/jvm}}
+{{#multiplatform}}
+* Kotlin 1.3.50
+{{/multiplatform}}
+
+## Build
+
+{{#jvm}}
+First, create the gradle wrapper script:
+
+```
+gradle wrapper
+```
+
+Then, run:
+
+{{/jvm}}
+```
+./gradlew check assemble
+```
+
+This runs all tests and packages the library.
+
+## Features/Implementation Notes
+
+{{#generateApiDocs}}
+<a name="documentation-for-api-endpoints"></a>
+## Documentation for API Endpoints
+
+All URIs are relative to *{{{basePath}}}*. Change it when instanciating `ApiClient(basePath)`.
+
+Class | Method | HTTP request | Description
+------------ | ------------- | ------------- | -------------
+{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | [**{{operationId}}**]({{apiDocPath}}{{classname}}.md#{{operationIdLowerCase}}) | **{{httpMethod}}** {{path}} | {{#summary}}{{{summary}}}{{/summary}}
+{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
+{{/generateApiDocs}}
+
+{{#generateModelDocs}}
+<a name="documentation-for-models"></a>
+## Documentation for Models
+
+{{#modelPackage}}
+{{#models}}{{#model}} - [{{{modelPackage}}}.{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
+{{/model}}{{/models}}
+{{/modelPackage}}
+{{^modelPackage}}
+No model defined in this package
+{{/modelPackage}}
+{{/generateModelDocs}}
+
+<a name="documentation-for-authorization"></a>{{! TODO: optional documentation for authorization? }}
+## Documentation for Authorization
+
+{{^authMethods}}
+All endpoints do not require authorization.
+{{/authMethods}}
+{{#authMethods}}
+{{#last}}
+Authentication schemes defined for the API:
+{{/last}}
+{{/authMethods}}
+{{#authMethods}}
+<a name="{{name}}"></a>
+### {{name}}
+
+{{#isApiKey}}- **Type**: API key
+- **API key parameter name**: {{keyParamName}}
+- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
+{{/isApiKey}}
+{{#isBasic}}- **Type**: HTTP basic authentication
+{{/isBasic}}
+{{#isOAuth}}- **Type**: OAuth
+- **Flow**: {{flow}}
+- **Authorization URL**: {{authorizationUrl}}
+- **Scopes**: {{^scopes}}N/A{{/scopes}}
+{{#scopes}}  - {{scope}}: {{description}}
+{{/scopes}}
+{{/isOAuth}}
+
+{{/authMethods}}
+
+## License
+
+Copyright (C) 2015-2020 PeerTube Contributors
+
+This 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.
+
+This 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.
+
+You 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 @@
+# Python API client for {{appName}}
+
+This Python package is automatically generated from [PeerTube's REST API](https://docs.joinpeertube.org/api-rest-reference.html),
+using the [OpenAPI Generator](https://openapi-generator.tech) project:
+
+- API version: {{appVersion}}
+- Package version: {{packageVersion}}
+{{^hideGenerationTimestamp}}
+- Build date: {{generatedDate}}
+{{/hideGenerationTimestamp}}
+- Build package: {{generatorClass}}
+
+{{#infoUrl}}
+For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
+{{/infoUrl}}
+
+## Requirements.
+
+Python 2.7 and 3.4+
+
+## Installation & Usage
+
+```sh
+pip install git+https://{{gitHost}}/{{{gitUserId}}}/{{{gitRepoId}}}.git
+```
+(you may need to run `pip` with root permission: `sudo pip install git+https://{{gitHost}}/{{{gitUserId}}}/{{{gitRepoId}}}.git`)
+
+Then import the package:
+```python
+import {{{packageName}}}
+```
+
+## Getting Started
+
+Please follow the [installation procedure](#installation--usage) and then run the following:
+
+{{> common_README }}
+
+## License
+
+Copyright (C) 2015-2020 PeerTube Contributors
+
+This 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.
+
+This 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.
+
+You 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