swagger: '2.0'
info:
  description: >
    This API is for developers that want to add a plaintext license to their 
    project but don't want to manually search the web for a copy.


    All API responses are strings, to make consuming the API via terminal or 
    console simple.
  version: 1.0.0
  title: Open Source Software License API
host: 'http://YOUR_WEBSITE.tld'
basePath: /
schemes:
  - http
paths:
  /api:
    get:
      tags:
        - List
      summary: List all available endpoints
      description: Returns a list of available endpoints
      produces:
        - text/plain
      responses:
        '200':
          description: Successful operation
          schema:
            $ref: '#/definitions/Endpoints'
          examples:
            text/plain: |
              ===============================================================
                                    Available Endpoints                      
              ===============================================================
                 Endpoint: /api/
              Description: List all available endpoints
              -
                 Endpoint: /api/list
              Description: List all available open source licenses by id
              ===============================================================
        '503':
          description: Service unavailable
          schema:
            $ref: '#/definitions/ErrorResponse'
          examples:
            text/plain: >
              ERROR - Endpoint list not found! Contact the site administrator if
              the problem persists.
  /api/list:
    get:
      tags:
        - List
      summary: List IDs of all available licenses
      description: >-
        Returns a list of available license IDs. Limited to **5** licenses per
        row for readability.
      produces:
        - text/plain
      responses:
        '200':
          description: Successful operation
          schema:
            $ref: '#/definitions/LicensesShort'
          examples:
            text/plain: |
              gpl-2.0, gpl-3.0, isc
        '503':
          description: Service unavailable
          schema:
            $ref: '#/definitions/ErrorResponse'
          examples:
            text/plain: >
              ERROR - License database not found! Contact the site administrator
              if the problem persists.
  /api/list/full:
    get:
      tags:
        - List
      summary: List IDs and names of all available licenses
      description: Returns a detailed list of available licenses
      produces:
        - text/plain
      responses:
        '200':
          description: Successful operation
          schema:
            $ref: '#/definitions/LicensesDetailed'
          examples:
            text/plain: |
              gpl-2.0             GNU General Public License v2.0
              gpl-3.0             GNU General Public License v3.0
              isc                 ISC License
        '503':
          description: Service unavailable
          schema:
            $ref: '#/definitions/ErrorResponse'
          examples:
            text/plain: >
              ERROR - License database not found! Contact the site administrator
              if the problem persists.
  '/api/{license}':
    get:
      tags:
        - License
      summary: Retrieve a license using its ID
      description: Returns a single license using its ID
      produces:
        - text/plain
      parameters:
        - name: license
          in: path
          description: The name of the license to retrieve
          required: true
          type: string
          format: string
      responses:
        '200':
          description: Successful operation
          schema:
            $ref: '#/definitions/LicenseText'
          examples:
            text/plain: >
              ISC License


              Copyright (c) [year], [fullname]


              Permission to use, copy, modify, and/or distribute this software
              for any purpose with or without fee is hereby granted, provided
              that the above copyright notice and this permission notice appear
              in all copies.


              THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
              WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
              WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
              AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
              CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
              LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
              NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
              CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
        '404':
          description: Not found
          schema:
            $ref: '#/definitions/ErrorResponse'
          examples:
            text/plain: >
              ERROR - NonExistentLicense is undefined. Use the 'list' endpoint
              to see defined license types.
definitions:
  Endpoints:
    type: string
  LicensesShort:
    type: string
  LicensesDetailed:
    type: string
  LicenseText:
    type: string
  ErrorResponse:
    type: string