api_doc.yml

swagger: '2.0'
info:
    title: Release Manager
    description: This application generate version for your software.
    contact:
        name: Vital Leshchyk
        url: https://github.com/itcreator/release-manager-micro
        email: vitalleshchyk@gmail.com
    license:
        name: 3-Clause BSD
        url: https://github.com/itcreator/release-manager-micro/blob/master/LICENSE
    version: 0.2.0

schemes:
    - http
#    - https

consumes:
    - application/release-manager.v1+json
produces:
    - application/release-manager.v1+json
tags:
    - name: project
      description: manages project
    - name: versionSemantic
      description: Generate version tag. See also http://semver.org/spec/v2.0.0.html

paths:
    /projects/{projectUuid}/version/semantic:
        parameters:
          - type: string
            format: uuid
            name: projectUuid
            description: Project ID in UUID format
            in: path
            required: true
        post:
            operationId: semverGenerate
            tags:
                - versionSemantic
            summary: Generate new semantic version number (based on gitflow)
            description: |
                Semantic Versioning 2.0.0
                See also http://semver.org/spec/v2.0.0.html
                Based on branching model [GitFlow](http://nvie.com/posts/a-successful-git-branching-model/)

            parameters:
                - name: body
                  in: body
                  schema:
                      $ref: "#/definitions/SemverGenerateParams"
            responses:
                201:
                    $ref: "#/responses/SemverGenerateResponse"
                404:
                    $ref: "#/responses/SemverProjectNotFoundResponse"
                500:
                    $ref: "#/responses/ErrorResponse"

    /projects:
        get:
            operationId: listProjects
            tags:
                - project
            summary: List the projects
            description: |
                Get all projects list.

            responses:
                200:
                    description: Successful response
#                    headers: ~
                    schema:
                        title: ProjectList
                        type: array
                        items:
                            $ref: "#/definitions/Project"
                500:
                    $ref: "#/responses/ErrorResponse"
        post:
            operationId: createProject
            tags:
                - project
            summary: Create new projects
            parameters:
                - name: body
                  in: body
                  schema:
                      $ref: "#/definitions/Project"
            responses:
                201:
                    $ref: "#/responses/ProjectResponse"
                500:
                    $ref: "#/responses/ErrorResponse"

    /projects/{uuid}:
        parameters:
            - type: string
              description: Project ID in UUID format
              format: uuid
              name: uuid
              in: path
              required: true
        get:
            operationId: readProject
            tags:
                - project
            summary: Read the projects
            description: |
                Get all projects list
            responses:
                200:
                    $ref: "#/responses/ProjectResponse"
                404:
                    $ref: "#/responses/ProjectResponse"
                500:
                    $ref: "#/responses/ErrorResponse"
        put:
            tags:
                - project
            operationId: updateProject
            parameters:
                - name: body
                  in: body
                  schema:
                      $ref: "#/definitions/Project"
            responses:
                200:
                    $ref: "#/responses/ProjectResponse"
                404:
                    $ref: "#/responses/ProjectResponse"
                500:
                    $ref: "#/responses/ErrorResponse"
responses:
    ErrorResponse:
        description: Error response
        headers:
            X-Error-Code:
                type: string
        schema:
            $ref: "#/definitions/Error"
    ProjectResponse:
        description: Project response
        headers:
            X-Error-Code:
                type: string
        schema:
            $ref: "#/definitions/Project"

    SemverGenerateResponse:
        description: Generate semantic version response
        schema:
            $ref: "#/definitions/SemverTagSet"

    SemverProjectNotFoundResponse:
        description: "Semver: project not found response"
        schema:
            $ref: "#/definitions/Error"

definitions:
    Error:
        title: Error Structure
        description: |
            Contains all the properties any error response from the API will contain.
            Some properties are optional so might be empty most of the time
        type: object
        required:
            - code
            - message
        properties:
            code:
                description: the error code, this is not necessarily the http status code
                type: integer
                format: int32
            message:
                description: a human readable version of the error
                type: string
            helpUrl:
                description: an optional url for getting more help about this error
                type: string
                format: uri

    Project:
        title: Project
        type: object
        required:
            - name
        properties:
            uuid:
                title: The id of the project.
                description: A unique identifier for the project. These are created in ascending order.
                type: string
                format: uuid
                readOnly: true
            name:
                title: The name of the project.
                type: string
                minLength: 2
                maxLength: 150
                x-nullable: false #don't generate reference
            description:
                title: The description of the project.
                type: string
                maxLength: 4000
                x-nullable: false #don't generate reference

    SemverGenerateParams:
        title: Paremeters for generate version number for project (Semantic Versioning)
        type: object
        required:
            - major
            - minor
            - branch
        properties:
            major:
                title: Major number
                description: MAJOR version when you make incompatible API changes
                type: integer
                format: uint32
                x-nullable: false #don't generate reference
            minor:
                title: Minor number
                description: MAJOR version when you make incompatible API changes
                type: integer
                format: uint32
                x-nullable: false #don't generate reference
            branch:
                title: Name of branch for which needed to generate a version tag.
                type: string
                minLength: 2
                maxLength: 150
                x-nullable: false #don't generate reference

    SemverTagSet:
        title: Semver set of tags
        type: object
        required:
            - full
            - isLatest
        properties:
            all:
                title: "Array of all tags (e.g: [latest, v1.2.1, v1.2, v1])"
                type: array
                items:
                  type: string
                x-nullable: false #don't generate reference
            full:
                title: "The full version tag (e.g: v1.2.1 or v1.2.0-rc.1 or v1.2.0-feature-22.1)"
                type: string
                minLength: 3
                maxLength: 150
                x-nullable: false #don't generate reference
            minor:
                title: "The minor version tag (e.g: v1.2)"
                type: string
                minLength: 3
                maxLength: 150
            major:
                title: "The minor version tag (e.g: v1)"
                type: string
                minLength: 3
                maxLength: 150
            branch:
                title: "The version tag which is generated for custom branch  (e.g: v1.2.0-rc for release branch)"
                type: string
                minLength: 3
                maxLength: 150
            isLatest:
                title: True if this version is latest. False - if not.
                type: boolean
                x-nullable: false #don't generate reference