aswi2021jmsd-gitlab4/src/swagger.yaml @ 3195e946

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