feat: migrate to openapi 3.0 generation

.circleci/config.yml

@@ -1,7 +1,7 @@
 version: 2.1
 
 orbs:
-  sdk: ory/[email protected].52
+  sdk: ory/[email protected].53
   changelog: ory/[email protected]
   goreleaser: ory/[email protected]
   slack: circleci/[email protected]
@@ -52,12 +52,21 @@ workflows:
               only: /.*/
             branches:
               only: master
-      - sdk/generate:
-          appname: Ory_Oathkeeper
-          swagpath: spec/api.json
+      - sdk/generate-openapi:
           requires:
             - test
-      - sdk/release:
+          filters:
+            tags:
+              only: /.*/
+            branches:
+              ignore: /master/
+      - sdk/test:
+          specpath: spec/api.json
+          generate: make sdk
+          filters:
+            tags:
+              only: /.*/
+      - sdk/release-openapi:
           swagpath: spec/api.json
           requires:
             - test

.schema/openapi/gen.go.yml

@@ -0,0 +1,6 @@
+disallowAdditionalPropertiesIfNotPresent: true
+packageName: client
+generateInterfaces: true
+isGoSubmodule: false
+structPrefix: true
+enumClassPrefix: true

.schema/openapi/gen.typescript.yml

@@ -0,0 +1,7 @@
+npmName: "@ory/kratos-client"
+npmVersion: 0.0.0
+# typescriptThreePlus: true
+#npmRepository: https://github.com/ory/sdk.git
+supportsES6: true
+ensureUniqueParams: true
+modelPropertyNaming: original

.schema/openapi/patches/health.yaml

@@ -0,0 +1,94 @@
+- op: replace
+  path: /paths/~1health~1alive
+  value:
+    get:
+      description: |-
+        This endpoint returns a HTTP 200 status code when {{.ProjectHumanName}} is accepting incoming
+        HTTP requests. This status does currently not include checks whether the database connection is working.
+
+        If the service supports TLS Edge Termination, this endpoint does not require the
+        `X-Forwarded-Proto` header to be set.
+
+        Be aware that if you are running multiple nodes of this service, the health status will never
+        refer to the cluster state, only to a single instance.
+      operationId: isAlive
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/healthStatus"
+          description: {{.ProjectHumanName}} is ready to accept connections.
+        '500':
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/genericError"
+          description: genericError
+      summary: Check HTTP Server Status
+      tags: {{ .HealthPathTags | toJson }}
+- op: replace
+  path: /paths/~1health~1ready
+  value:
+    get:
+      operationId: isReady
+      description: |-
+        This endpoint returns a HTTP 200 status code when {{.ProjectHumanName}} is up running and the environment dependencies (e.g.
+        the database) are responsive as well.
+
+        If the service supports TLS Edge Termination, this endpoint does not require the
+        `X-Forwarded-Proto` header to be set.
+
+        Be aware that if you are running multiple nodes of {{.ProjectHumanName}}, the health status will never
+        refer to the cluster state, only to a single instance.
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    description: Always "ok".
+                    type: string
+          description: {{.ProjectHumanName}} is ready to accept requests.
+        '503':
+          content:
+            application/json:
+              schema:
+                properties:
+                  errors:
+                    additionalProperties:
+                      type: string
+                    description: Errors contains a list of errors that caused the not ready status.
+                    type: object
+                type: object
+          description: Ory Kratos is not yet ready to accept requests.
+      summary: Check HTTP Server and Database Status
+      tags: {{ .HealthPathTags | toJson }}
+- op: replace
+  path: /paths/~1version
+  value:
+    get:
+      description: |-
+        This endpoint returns the version of {{.ProjectHumanName}}.
+
+        If the service supports TLS Edge Termination, this endpoint does not require the
+        `X-Forwarded-Proto` header to be set.
+
+        Be aware that if you are running multiple nodes of this service, the version will never
+        refer to the cluster state, only to a single instance.
+      operationId: getVersion
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  version:
+                    description: The version of {{.ProjectHumanName}}.
+                    type: string
+          description: Returns the {{.ProjectHumanName}} version.
+      summary: Return Running Software Version.
+      tags: {{ .HealthPathTags | toJson }}

.schema/openapi/patches/meta.yaml

@@ -0,0 +1,12 @@
+- op: replace
+  path: /info
+  value:
+    title: Ory Oathkeeper API
+    description: |
+      Documentation for all of Ory Oathkeeper's APIs.
+    version: >-
+      {{ getenv "CIRCLE_TAG" }}
+    license:
+      name: Apache 2.0
+    contact:
+      email: "[email protected]"

.schema/openapi/templates/go/.travis.yml

@@ -0,0 +1,8 @@
+language: go
+
+install:
+  - go get -d -v .
+
+script:
+  - go build -v ./
+

.schema/openapi/templates/go/README.mustache

@@ -0,0 +1,221 @@
+# Go API client for {{packageName}}
+
+{{#appDescriptionWithNewLines}}
+{{{appDescriptionWithNewLines}}}
+{{/appDescriptionWithNewLines}}
+
+## Overview
+This API client was generated by the [OpenAPI Generator](https://openapi-generator.tech) project.  By using the [OpenAPI-spec](https://www.openapis.org/) from a remote server, you can easily generate an API client.
+
+- 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
+```
+
+Put the package under your project folder and add the following in import:
+
+```golang
+import {{packageName}} "{{gitHost}}/{{gitUserId}}/{{gitRepoId}}{{#isGoSubmodule}}/{{packageName}}{{/isGoSubmodule}}"
+```
+
+To use a proxy, set the environment variable `HTTP_PROXY`:
+
+```golang
+os.Setenv("HTTP_PROXY", "http://proxy_name:proxy_port")
+```
+
+## Configuration of Server URL
+
+Default configuration comes with `Servers` field that contains server objects as defined in the OpenAPI specification.
+
+### Select Server Configuration
+
+For using other server than the one defined on index 0 set context value `sw.ContextServerIndex` of type `int`.
+
+```golang
+ctx := context.WithValue(context.Background(), {{packageName}}.ContextServerIndex, 1)
+```
+
+### Templated Server URL
+
+Templated server URL is formatted using default variables from configuration or from context value `sw.ContextServerVariables` of type `map[string]string`.
+
+```golang
+ctx := context.WithValue(context.Background(), {{packageName}}.ContextServerVariables, map[string]string{
+	"basePath": "v2",
+})
+```
+
+Note, enum values are always validated and all unused variables are silently ignored.
+
+### URLs Configuration per Operation
+
+Each operation can use different server URL defined using `OperationServers` map in the `Configuration`.
+An operation is uniquely identifield by `"{classname}Service.{nickname}"` string.
+Similar rules for overriding default operation server index and variables applies by using `sw.ContextOperationServerIndices` and `sw.ContextOperationServerVariables` context maps.
+
+```
+ctx := context.WithValue(context.Background(), {{packageName}}.ContextOperationServerIndices, map[string]int{
+	"{classname}Service.{nickname}": 2,
+})
+ctx = context.WithValue(context.Background(), {{packageName}}.ContextOperationServerVariables, map[string]map[string]string{
+	"{classname}Service.{nickname}": {
+		"port": "8443",
+	},
+})
+```
+
+## 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
+- **API key parameter name**: {{{keyParamName}}}
+- **Location**: {{#isKeyInQuery}}URL query string{{/isKeyInQuery}}{{#isKeyInHeader}}HTTP header{{/isKeyInHeader}}
+
+Note, each API key must be added to a map of `map[string]APIKey` where the key is: {{keyParamName}} and passed in as the auth context for each request.
+
+{{/isApiKey}}
+{{#isBasic}}
+{{#isBasicBearer}}
+- **Type**: HTTP Bearer token authentication
+
+Example
+
+```golang
+auth := context.WithValue(context.Background(), sw.ContextAccessToken, "BEARER_TOKEN_STRING")
+r, err := client.Service.Operation(auth, args)
+```
+
+{{/isBasicBearer}}
+{{#isBasicBasic}}
+- **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)
+```
+
+{{/isBasicBasic}}
+{{#isHttpSignature}}
+- **Type**: HTTP signature authentication
+
+Example
+
+```golang
+	authConfig := client.HttpSignatureAuth{
+		KeyId:                "my-key-id",
+		PrivateKeyPath:       "rsa.pem",
+		Passphrase:           "my-passphrase",
+		SigningScheme:        sw.HttpSigningSchemeHs2019,
+		SignedHeaders:        []string{
+			sw.HttpSignatureParameterRequestTarget, // The special (request-target) parameter expresses the HTTP request target.
+			sw.HttpSignatureParameterCreated,       // Time when request was signed, formatted as a Unix timestamp integer value.
+			"Host",                                 // The Host request header specifies the domain name of the server, and optionally the TCP port number.
+			"Date",                                 // The date and time at which the message was originated.
+			"Content-Type",                         // The Media type of the body of the request.
+			"Digest",                               // A cryptographic digest of the request body.
+		},
+		SigningAlgorithm:     sw.HttpSigningAlgorithmRsaPSS,
+		SignatureMaxValidity: 5 * time.Minute,
+	}
+	var authCtx context.Context
+	var err error
+	if authCtx, err = authConfig.ContextWithValue(context.Background()); err != nil {
+		// Process error
+	}
+	r, err = client.Service.Operation(auth, args)
+
+```
+{{/isHttpSignature}}
+{{/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}}
+
+## Documentation for Utility Methods
+
+Due to the fact that model structure members are all pointers, this package contains
+a number of utility functions to easily obtain pointers to values of basic types.
+Each of these functions takes a value of the given basic type and returns a pointer to it:
+
+* `PtrBool`
+* `PtrInt`
+* `PtrInt32`
+* `PtrInt64`
+* `PtrFloat`
+* `PtrFloat32`
+* `PtrFloat64`
+* `PtrString`
+* `PtrTime`
+
+## Author
+
+{{#apiInfo}}{{#apis}}{{#-last}}{{infoEmail}}
+{{/-last}}{{/apis}}{{/apiInfo}}