refactor: move documentation to ory/docs and move to OAS3.0 generator (…

…#833)

Co-authored-by: zepatrik <zepatrik@users.noreply.github.com>

.github/workflows/ci.yaml

@@ -7,6 +7,10 @@ on:
       - '*'
   pull_request:
 
+# Cancel in-progress runs in current workflow.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
   validate:
@@ -22,12 +26,6 @@ jobs:
       - run: go list -json > go.list
       - name: Run nancy
         uses: sonatype-nexus-community/nancy-github-action@v1.0.2
-      - name: Run prettier
-        uses: ory/ci/prettier@master
-      - name: Run prettier (docs)
-        uses: ory/ci/prettier@master
-        with:
-          dir: docs
       - name: Run golangci-lint
         uses: golangci/golangci-lint-action@v2
         env:
@@ -97,17 +95,28 @@ jobs:
 
   docs-build:
     runs-on: ubuntu-latest
-    name: Build and publish docs
+    name: Synchronize autogenerated files to docs
     if: ${{ startsWith(github.ref, 'refs/tags/v') || github.ref_name == 'master' }}
     needs:
       - test
       - test-race
       - validate
     steps:
-      - uses: ory/ci/docs/build@master
+      - uses: ory/ci/docs/sync@master
         with:
           token: ${{ secrets.ORY_BOT_PAT }}
-          swag-spec-location: spec/api.json
+          api-spec-location: spec/api.json
+          config-spec-location: .schema/config.schema.json
+      - env:
+          GITHUB_TOKEN: ${{ inputs.token }}
+        run: |
+          cp "current-repo/docs/.generated/proto-api.mdx" "docs/docs/keto/reference/proto-api.mdx"
+          cd docs
+          git add -A
+          git commit -a -m "autogen(docs): generate and bump docs for $repo" || true
+          git pull origin master --rebase || true
+          git push origin HEAD:master || true
+        shell: bash
 
   docs-cli:
     runs-on: ubuntu-latest
@@ -117,9 +126,10 @@ jobs:
       - test-race
       - validate
     steps:
-      - uses: ory/ci/docs/cli@master
+      - uses: ory/ci/docs/cli-next@master
         with:
           token: ${{ secrets.ORY_BOT_PAT }}
+          output-dir: docs/keto/cli
 
   changelog:
     name: Generate changelog
@@ -244,3 +254,52 @@ jobs:
           mailchimp_api_key: ${{ secrets.MAILCHIMP_API_KEY }}
           draft: 'false'
           ssh_key: ${{ secrets.ORY_BOT_SSH_KEY }}
+
+  buf:
+    name: Run buf actions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          path: current-repo
+      - uses: actions/setup-go@v2
+        with:
+          go-version: '1.17'
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '15'
+      - uses: arduino/setup-protoc@v1
+        with:
+          version: '3.12.x'
+      - name: Lint and Build
+        run: make buf
+        working-directory: current-repo
+      - name: Format Docs (required because buf generates the proto docs)
+        run: |
+          make format
+        working-directory: current-repo
+      - name: Push build
+        run: |
+          git config --local user.email "60093411+ory-bot@users.noreply.github.com"
+          git config --local user.name "ory-bot"
+          git add proto
+          git commit -a -m "autogen: build buf" && git push "https://${GITHUB_ACTOR}:${ORY_BOT_PAT}@github.com/${GITHUB_REPOSITORY}.git" HEAD:${GITHUB_REF#"refs/heads/"} || true
+        working-directory: current-repo
+      - name: Push docs to master
+        run: |
+          git config --local user.email "60093411+ory-bot@users.noreply.github.com"
+          git config --local user.name "ory-bot"
+          git add proto
+          git commit -a -m "autogen: build buf" && git push "https://${GITHUB_ACTOR}:${ORY_BOT_PAT}@github.com/${GITHUB_REPOSITORY}.git" HEAD:${GITHUB_REF#"refs/heads/"} || true
+        working-directory: current-repo
+      - if: ${{ github.ref_name == 'master' || github.ref_type == 'tag' }}
+        name: Push build to docs
+        env:
+          GITHUB_TOKEN: ${{ inputs.token || github.token }}
+        run: |
+          cd docs
+          git stash || true
+          git pull --rebase origin ${{ inputs.docs-branch }} || true
+          git stash apply || true
+          git push origin HEAD:${{ inputs.docs-branch }} || true
+        shell: bash

.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: "hi@ory.sh"

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

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