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.

diff --git a/scripts/openapi-clients.sh b/scripts/openapi-clients.sh
index b031ceac1194be5c7776818c0f3c4a029913c622..c799658e39ae23819278aa5765c85de054e61e5c 100755 (executable)
--- 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.yaml b/support/openapi/go.yaml
deleted file mode 100644 (file)
index 7136da9..0000000
--- a/support/openapi/go.yaml
+++ /dev/null
@@ -1,3 +0,0 @@
-# https://openapi-generator.tech/docs/generators/go
-
-packageName: peertube

diff --git a/support/openapi/go/README.mustache b/support/openapi/go/README.mustache
new file mode 100644 (file)
index 0000000..d0fc0fa
--- /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/def.yaml b/support/openapi/go/def.yaml
new file mode 100644 (file)
index 0000000..7136da9
--- /dev/null
+++ b/support/openapi/go/def.yaml
@@ -0,0 +1,3 @@
+# https://openapi-generator.tech/docs/generators/go
+
+packageName: peertube

diff --git a/support/openapi/kotlin.yaml b/support/openapi/kotlin.yaml
deleted file mode 100644 (file)
index 7a01ae6..0000000
--- a/support/openapi/kotlin.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# https://openapi-generator.tech/docs/generators/kotlin
-
-artifactId: peertube-api
-groupId: org.peertube
-packageName: org.peertube.client
-

diff --git a/support/openapi/kotlin/README.mustache b/support/openapi/kotlin/README.mustache
new file mode 100644 (file)
index 0000000..ac7fbde
--- /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/def.yaml b/support/openapi/kotlin/def.yaml
new file mode 100644 (file)
index 0000000..7a01ae6
--- /dev/null
+++ b/support/openapi/kotlin/def.yaml
@@ -0,0 +1,6 @@
+# https://openapi-generator.tech/docs/generators/kotlin
+
+artifactId: peertube-api
+groupId: org.peertube
+packageName: org.peertube.client
+

diff --git a/support/openapi/python.yaml b/support/openapi/python.yaml
deleted file mode 100644 (file)
index 819a466..0000000
--- a/support/openapi/python.yaml
+++ /dev/null
@@ -1,5 +0,0 @@
-# https://openapi-generator.tech/docs/generators/python
-
-packageName: peertube
-projectName: peertube
-

diff --git a/support/openapi/python/README.mustache b/support/openapi/python/README.mustache
new file mode 100644 (file)
index 0000000..93dcd5a
--- /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/def.yaml b/support/openapi/python/def.yaml
new file mode 100644 (file)
index 0000000..819a466
--- /dev/null
+++ b/support/openapi/python/def.yaml
@@ -0,0 +1,5 @@
+# https://openapi-generator.tech/docs/generators/python
+
+packageName: peertube
+projectName: peertube
+