swagger_talk_swagger.yml

    swagger: '2.0'
    info:
        title: DEMO API
        description: Demonstration for techtalk @ ferret
        version: 1.0.0
        termsOfService: http://demo.berlin/terms/
        contact:
            name: API Support
            url: http://demo.berlin/support
            email: support@demo.berlin
        license:
            name: Apache 2.0
            url: http://www.apache.org/licenses/LICENSE-2.0.html
    host: api.demo.berlin
    schemes:
      - http
      - https
    basePath: /v1
    consumes:
      - application/json
    produces:
      - application/json
    paths:
        /articles:
            get:
                summary: Get Articles
                operationId: getArticles
                parameters:
                  - name: size
                    in: query
                    required: false
                    default: 10
                    maximum: 100
                    type: integer
                    format: int32
                  - name: offset
                    in: query
                    required: false
                    default: 1
                    type: integer
                    format: int32
                tags:
                  - Articles
                responses:
                    200:
                        description: An array of articles
                        schema:
                            $ref: "#/definitions/Articles"
                    default:
                        description: Unexpected error
                        schema:
                            $ref: "#/definitions/Error"
        /article/{id}/authors:
            get:
                summary: Get Authors
                operationId: getAuthorsByArticleID
                description: The Authors endpoint returns all authors for the specific article identified by {id}
                parameters:
                  - name: id
                    in: path
                    description: Id of the Article
                    required: true
                    type: string
                tags:
                  - Articles
                  - Authors
                responses:
                    200:
                        description: An array of authors
                        schema:
                            $ref: "#/definitions/Authors"
                    404:
                        description: Article Not Found
                        schema:
                            $ref: "#/definitions/Error"
                    default:
                        description: Unexpected error
                        schema:
                            $ref: "#/definitions/Error"
    definitions:
        Article:
            properties:
                id:
                    type: string
                    description: Unique identifier.
                title:
                    type: string
                    description: Title of the article.
                text:
                    type: string
                    description: Text of the article.
                authors:
                    type: array
                    items:
                        $ref: "#/definitions/Author"
        Articles:
            properties:
                offset:
                    type: integer
                    format: int32
                    description: Position in pagination.
                size:
                    type: integer
                    format: int32
                    description: Number of articles to retrieve (100 max).
                total:
                    type: integer
                    format: int32
                    description: Total number of articles available.
                items:
                    type: array
                    items:
                        $ref: "#/definitions/Article"
        Author:
            properties:
                id:
                    type: string
                    description: Unique identifier.
                name:
                    type: string
                    description: Name of the author.
                email:
                    type: string
                    description: Author’s email.
        Authors:
            properties:
                total:
                    type: integer
                    format: int32
                    description: Total number of authors.
                items:
                    type: array
                    items:
                        $ref: "#/definitions/Author"
        Error:
            properties:
                code:
                    type: integer
                    format: int32
                message:
                    type: string
                fields:
                    type: string
    tags:
      - name: Articles
        description: Articles operations
      - name: Authors
        description: Authors operations
    externalDocs:
        description: Find more info here
        url: https://docs.demo.berlin