Document API with OpenAPI/Swagger/API Blueprint

[arthurlutz]

It would be nice to have some API documentation with standard formats for APIs

• https://www.openapis.org/
• https://apiblueprint.org/

As a bonus, maybe Dredd can be used to have an "executable" API documentation https://github.com/apiaryio/dredd

[JustinBack]

I am currently working on a swagger 2.0 specification with the new API available at https://beta.tosdr.org

[JustinBack]

The first version of the data specification is now ready.

swagger: "2.0"
info:
  description: "We encourage people to develop applications and other services integrating our ratings into their work. This page should help you use our data for your own app. Our source code is on Github."
  version: "1.0.0"
  title: "Terms of Service; Didn't Read"
  termsOfService: "https://beta.tosdr.org/en/legal"
  contact:
    email: "team@tosdr.org"
  license:
    name: "Creative commons"
    url: "http://creativecommons.org/licenses/by-sa/3.0/"
host: "beta.tosdr.org"
basePath: "/api/"
tags:
- name: "Service"
  description: "Get the points, documents, links and ratings of a service"
  externalDocs:
    description: "GitHub"
    url: "https://github.com/JustinBack/CrispCMS-ToS-DR/blob/master/api/api.php"
- name: "Badges"
  description: "Access vector badges of a service"
schemes:
- "https"
- "http"
paths:
  /1/{serviceID}:
    get:
      tags:
      - "Service"
      summary: "Get a service by its ID"
      description: "Returns a service"
      produces:
      - "application/json"
      parameters:
      - name: "serviceID"
        in: "path"
        description: "ID of service to return"
        required: true
        type: "integer"
        format: "int64"
      responses:
        "200":
          description: "successful operation"
          schema:
            $ref: "#/definitions/Service"
        default:
          description: "An error occurred"
          schema:
            $ref: "#/definitions/Error"
  /1/service/{serviceSlug}:
    get:
      tags:
      - "Service"
      summary: "Get a service by its Slug"
      description: "Returns a service"
      produces:
      - "application/json"
      parameters:
      - name: "serviceSlug"
        in: "path"
        description: "Slug of service to return"
        required: true
        type: "string"
      responses:
        "200":
          description: "successful operation"
          schema:
            $ref: "#/definitions/Service"
        default:
          description: "An error occurred"
          schema:
            $ref: "#/definitions/Error"
  /badge/service/{serviceID}:
    get:
      tags:
      - "Badges"
      summary: "Get a service badge by its ID"
      description: "Returns a service"
      produces:
      - "application/json"
      parameters:
      - name: "serviceID"
        in: "path"
        description: "ID of service to return"
        required: true
        type: "integer"
        format: "int64"
      responses:
        "200":
          description: "The Badge in SVG format"
          
        default:
          description: "An error occurred"
          schema:
            $ref: "#/definitions/Error"
definitions: 
  Service:
    properties:
      alexa: 
        type: integer
        format: nullable
      class: 
        type: string
        enum:
        - "A"
        - "B"
        - "C"
        - "D"
        - "F"
        - "N/A"
      links: 
        type: object
        properties: 
          "Document Title": 
            type: object
            properties: 
              name: 
                type: string
              url: 
                type: string
      points: 
        type: array
        items: 
          type: integer
      pointsData: 
        type: object
        properties: 
          point_id: 
            type: object
            properties: 
              discussion: 
                type: string
              id: 
                type: integer
                format: int32
              needsModeration: 
                type: boolean
              quoteDoc: 
                type: string
              quoteText: 
                type: string
              quoteStart: 
                type: integer
                format: int32
              quoteEnd: 
                type: integer
                format: int32
              services: 
                type: array
                items: 
                  type: string
              set: 
                type: string
              slug: 
                type: string
              title: 
                type: string
              topics:
                type: array
                items:
                  type: integer
              tosdr: 
                type: object
                properties: 
                  binding: 
                    type: boolean
                  case: 
                    type: string
                  point: 
                    type: string
                  score: 
                    type: integer
                    format: int32
                  tldr: 
                    type: string
      urls: 
        type: array
        items: 
          type: string
  Error:
    properties:
        error: 
          type: array
          items: 
            type: string
        message: 
          type: string
        parameters: 
          type: array
          items: 
            type: string

[JustinBack]

Swagger UI has now been implemented with 073bb86 and is available at https://tosdr.org/swagger/