Revize f716748a

Re #8476 - Added swagger.yaml (created by Jan Pašek).

swagger_server/swagger/swagger.yaml

@@ +1 @@
+openapi: 3.0.0
+info:
+  title: X.509 certificate management
+  description: API for certificate management created for YOSO company
+  version: 1.0.1
+servers:
+- url: https://virtserver.swaggerhub.com/janpasek97/X509_management/1.0.1
+  description: X509 management API
+tags:
+- name: certificates
+  description: API for creating and querying certificates
+paths:
+  /api/certificates/{id}:
+    get:
+      tags:
+      - certificates
+      summary: get certificate by ID
+      description: Get certificate in PEM format by ID
+      operationId: get_certificate_by_id
+      parameters:
+      - name: id
+        in: path
+        description: ID of a certificate to be queried
+        required: true
+        style: simple
+        explode: false
+        schema:
+          $ref: '#/components/schemas/IdParameter'
+      responses:
+        "200":
+          description: returning the certificate
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PemResponse'
+        "204":
+          description: the certificate was not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        "400":
+          description: bad request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+      x-openapi-router-controller: swagger_server.controllers.certificates_controller
+  /api/certificates/{id}/chain:
+    get:
+      tags:
+      - certificates
+      summary: get certificate's trust chain by ID
+      description: Get certificate trust chain in PEM format by ID
+      operationId: get_certificate_trust_chain_by_id
+      parameters:
+      - name: id
+        in: path
+        description: ID of a child certificate whose chain is to be queried
+        required: true
+        style: simple
+        explode: false
+        schema:
+          $ref: '#/components/schemas/IdParameter'
+      responses:
+        "200":
+          description: returning the trust chain
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PemResponse'
+        "204":
+          description: the certificate was not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        "400":
+          description: bad request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+      x-openapi-router-controller: swagger_server.controllers.certificates_controller
+  /api/certificates/{id}/root:
+    get:
+      tags:
+      - certificates
+      summary: get certificate's root of trust chain by ID
+      description: Get certificate's root of trust chain in PEM format by ID
+      operationId: get_certificate_root_by_id
+      parameters:
+      - name: id
+        in: path
+        description: ID of a child certificate whose root is to be queried
+        required: true
+        style: simple
+        explode: false
+        schema:
+          $ref: '#/components/schemas/IdParameter'
+      responses:
+        "200":
+          description: returning the root of trust chain
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PemResponse'
+        "204":
+          description: the certificate was not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        "400":
+          description: bad request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+      x-openapi-router-controller: swagger_server.controllers.certificates_controller
+  /api/certificates/{id}/details:
+    get:
+      tags:
+      - certificates
+      summary: get certificate's details by ID
+      description: Get certificate details by ID
+      operationId: get_certificate_details_by_id
+      parameters:
+      - name: id
+        in: path
+        description: ID of a certificate whose details are to be queried
+        required: true
+        style: simple
+        explode: false
+        schema:
+          $ref: '#/components/schemas/IdParameter'
+      responses:
+        "200":
+          description: returning the certificate details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CertificateResponse'
+        "204":
+          description: the certificate was not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        "400":
+          description: bad request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+      x-openapi-router-controller: swagger_server.controllers.certificates_controller
+  /api/certificates:
+    get:
+      tags:
+      - certificates
+      summary: get list of certificates
+      description: Lists certificates based on provided filtering options
+      operationId: get_certificate_list
+      parameters:
+      - name: filtering
+        in: query
+        description: Filter certificate type to be queried
+        required: false
+        style: form
+        explode: true
+        schema:
+          $ref: '#/components/schemas/Filtering'
+      responses:
+        "200":
+          description: returning results matching filtering criteria
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CertificateListResponse'
+        "204":
+          description: no certificates found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        "400":
+          description: bad request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+      x-openapi-router-controller: swagger_server.controllers.certificates_controller
+    post:
+      tags:
+      - certificates
+      summary: create new certificate
+      description: Create a new certificate based on given information
+      operationId: create_certificate
+      requestBody:
+        description: Certificate data to be created
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CertificateRequest'
+      responses:
+        "201":
+          description: item created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CreatedResponse'
+        "400":
+          description: "invalid input, object invalid"
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        "409":
+          description: an existing item already exists
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+      x-openapi-router-controller: swagger_server.controllers.certificates_controller
+components:
+  schemas:
+    CAUsage:
+      required:
+      - CA
+      - SSL
+      - authentication
+      - digitalSignature
+      properties:
+        CA:
+          type: boolean
+        authentication:
+          type: boolean
+        digitalSignature:
+          type: boolean
+        SSL:
+          type: boolean
+      example:
+        digitalSignature: true
+        SSL: true
+        CA: true
+        authentication: true
+    IssuerListItem:
+      required:
+      - CN
+      - id
+      properties:
+        id:
+          type: integer
+          example: 547
+        CN:
+          type: string
+          example: Root CA s.r.o.
+      example:
+        id: 547
+        CN: Root CA s.r.o.
+    CertificateListResponse:
+      properties:
+        success:
+          type: boolean
+          example: true
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/CertificateListItem'
+      example:
+        data:
+        - notAfter: 2021-07-01T00:00:00.000+00:00
+          usage:
+            digitalSignature: true
+            SSL: true
+            CA: true
+            authentication: true
+          id: 547
+          CN: Root CA s.r.o.
+          notBefore: 2021-03-31T00:00:00.000+00:00
+          issuer:
+            id: 547
+            CN: Root CA s.r.o.
+        - notAfter: 2021-07-01T00:00:00.000+00:00
+          usage:
+            digitalSignature: true
+            SSL: true
+            CA: true
+            authentication: true
+          id: 547
+          CN: Root CA s.r.o.
+          notBefore: 2021-03-31T00:00:00.000+00:00
+          issuer:
+            id: 547
+            CN: Root CA s.r.o.
+        success: true
+    CertificateListItem:
+      properties:
+        id:
+          type: integer
+          example: 547
+        CN:
+          type: string
+          example: Root CA s.r.o.
+        notBefore:
+          type: string
+          format: date
+          example: 2021-03-31
+        notAfter:
+          type: string
+          format: date
+          example: 2021-07-01
+        usage:
+          $ref: '#/components/schemas/CAUsage'
+        issuer:
+          $ref: '#/components/schemas/IssuerListItem'
+      example:
+        notAfter: 2021-07-01T00:00:00.000+00:00
+        usage:
+          digitalSignature: true
+          SSL: true
+          CA: true
+          authentication: true
+        id: 547
+        CN: Root CA s.r.o.
+        notBefore: 2021-03-31T00:00:00.000+00:00
+        issuer:
+          id: 547
+          CN: Root CA s.r.o.
+    Filtering:
+      properties:
+        CA:
+          type: boolean
+    Subject:
+      required:
+      - CN
+      properties:
+        C:
+          type: string
+          description: Country code
+          example: CZ
+        ST:
+          type: string
+          description: State/Province
+          example: Pilsen Region
+        L:
+          type: string
+          description: Locality
+          example: Pilsen
+        CN:
+          type: string
+          description: Common name
+          example: Root CA s.r.o.
+        O:
+          type: string
+          description: Organization
+          example: Root CA s.r.o.
+        OU:
+          type: string
+          description: Organization Unit
+          example: IT department
+        emailAddress:
+          type: string
+          description: Email Address
+          example: [e-mail]
+      example:
+        ST: Pilsen Region
+        emailAddress: [e-mail]
+        C: CZ
+        OU: IT department
+        CN: Root CA s.r.o.
+        L: Pilsen
+        O: Root CA s.r.o.
+    Certificate:
+      required:
+      - notAfter
+      - notBefore
+      - subject
+      - usage
+      properties:
+        subject:
+          $ref: '#/components/schemas/Subject'
+        notBefore:
+          type: string
+          format: date
+          example: 2021-03-31
+        notAfter:
+          type: string
+          format: date
+          example: 2021-07-01
+        usage:
+          $ref: '#/components/schemas/CAUsage'
+        CA:
+          type: integer
+          description: ID of the new item
+          example: 547
+      example:
+        notAfter: 2021-07-01T00:00:00.000+00:00
+        subject:
+          ST: Pilsen Region
+          emailAddress: [e-mail]
+          C: CZ
+          OU: IT department
+          CN: Root CA s.r.o.
+          L: Pilsen
+          O: Root CA s.r.o.
+        usage:
+          digitalSignature: true
+          SSL: true
+          CA: true
+          authentication: true
+        notBefore: 2021-03-31T00:00:00.000+00:00
+        CA: 547
+    CertificateRequest:
+      required:
+      - subject
+      - usage
+      - validityDays
+      properties:
+        subject:
+          $ref: '#/components/schemas/Subject'
+        validityDays:
+          type: integer
+          example: 30
+        usage:
+          $ref: '#/components/schemas/CAUsage'
+        CA:
+          type: integer
+          description: ID of the new item
+          example: 547
+    CreatedResponse:
+      required:
+      - data
+      - success
+      properties:
+        success:
+          type: boolean
+          example: true
+        data:
+          type: integer
+          example: 457
+      description: Item was created
+      example:
+        data: 457
+        success: true
+    ErrorResponse:
+      required:
+      - data
+      - success
+      properties:
+        success:
+          type: boolean
+          example: false
+        data:
+          type: string
+          example: An error occured
+    CertificateResponse:
+      required:
+      - data
+      - success
+      properties:
+        success:
+          type: boolean
+          example: true
+        data:
+          $ref: '#/components/schemas/Certificate'
+      example:
+        data:
+          notAfter: 2021-07-01T00:00:00.000+00:00
+          subject:
+            ST: Pilsen Region
+            emailAddress: [e-mail]
+            C: CZ
+            OU: IT department
+            CN: Root CA s.r.o.
+            L: Pilsen
+            O: Root CA s.r.o.
+          usage:
+            digitalSignature: true
+            SSL: true
+            CA: true
+            authentication: true
+          notBefore: 2021-03-31T00:00:00.000+00:00
+          CA: 547
+        success: true
+    PemResponse:
+      required:
+      - data
+      - success
+      properties:
+        success:
+          type: boolean
+          example: true
+        data:
+          type: string
+          description: Single PEM file or concatenation of multiple PEM formatted
+            certificates
+          example: '-----BEGIN CERTIFICATE-----MIICLDCCAdKgAwIBAgIBADAKBggqhkjOPQQDAjB9MQswCQYDVQQGEwJCRTEPMA0GA1UEChMGR251VExTMSUwIwYDVQQ...etc-----END
+            CERTIFICATE-----'
+      example:
+        data: '-----BEGIN CERTIFICATE-----MIICLDCCAdKgAwIBAgIBADAKBggqhkjOPQQDAjB9MQswCQYDVQQGEwJCRTEPMA0GA1UEChMGR251VExTMSUwIwYDVQQ...etc-----END
+          CERTIFICATE-----'
+        success: true
+    IdParameter:
+      required:
+      - id
+      properties:
+        id:
+          type: integer
+          example: 444
+