swagger: '2.0'
info:
  version: '1.0.0-beta'
  title: MediaWiki Citation API
  description: Citation API based on the Citoid services
  termsOfService: https://github.com/wikimedia/restbase#restbase
  contact:
    name: Services
    email: services@lists.wikimedia.org
    url: https://www.mediawiki.org/wiki/Services
  license:
    name: Apache licence, v2
    url: https://www.apache.org/licenses/LICENSE-2.0
paths:
  /citation/{format}/{query}:
    get:
      tags:
        - Citation
      summary: Get citation data given an article identifier.
      description: |
        Generates citation data given a URL, DOI, PMID, ISBN, or PMCID.

        See more at [Citoid service documentation](https://www.mediawiki.org/wiki/Citoid)

        The citation data can be requested in one of the following formats:
          - `mediawiki`: format designed for MediaWiki to be used with `templateData`.
            Uses [Zotero field names](https://aurimasv.github.io/z2csl/typeMap.xml).
          - `mediawiki-basefields`: `mediawiki` format with Zotero `basefield` field names.
          - `zotero`: format used by [Zotero](https://www.zotero.org/).
          - `bibtex`: format used in conjunction with LaTeX documents.
            See [bibtex.org](http://www.bibtex.org/).

        Stability: [unstable](https://www.mediawiki.org/wiki/API_versioning#Unstable)
      produces:
        - application/json; charset=utf-8;
        - application/x-bibtex; charset=utf-8
      parameters:
        - name: format
          in: path
          description: "The format to use for the resulting citation data"
          enum:
            - mediawiki
            - mediawiki-basefields
            - zotero
            - bibtex
          required: true
        - name: query
          in: path
          description: >
            URL of an article, DOI, ISBN, PMCID or PMID in the URL-encoded format.
            Note that on the Swagger-UI doc page you don't need to URI-encode the
            parameter manually, it will be done by the docs engine.
          type: string
          required: true
        - name: Accept-Language
          in: header
          type: string
          required: false
          description: >
            For some articles the result depends on the `Accept-Language` header, so
            provide it if localized content is required.
      responses:
        '200':
          description: The citation data in the requested format
          schema:
            $ref: '#/definitions/result'
        '404':
          description: Citation data was not found.
          schema:
            $ref: '#/definitions/problem'

      operationId: getCitation
      x-monitor: true
      x-amples:
        - title: Get citation for Darth Vader
          request:
            params:
              domain: en.wikipedia.org
              format: mediawiki
              query: 'https://en.wikipedia.org/wiki/Darth_Vader'
          response:
            status: 200
            headers:
              content-type:  /^application\/json/
            body:
              - title: 'Darth Vader'
                language: en
                itemType: encyclopediaArticle
                encyclopediaTitle: Wikipedia

definitions:
  result:
    required:
      - title
      - url
      - itemType
    properties:
      itemType:
        type: string
      title:
        type: string
      url:
        type: string