Goophr Concierge is the user-facing component, and it has two responsibilities—to index new documents and to return query results. Informally, we can define the API as follows:

• /api/feeder: This is the API endpoint to upload documents by user
  • The POST request adds new documents if the payload is complete and correct
• /api/query: The user searches for phrases or terms that are queried against this API endpoint
  • The POST request contains payload with search terms, and a list of documents will be returned

This simple API description is for our understanding. Now let's look at how this would be formulated using the OpenAPI specification:

# openapi/concierge.yaml

openapi: 3.0.0

servers: 
  - url: /api 
info: 
  title: Goophr Concierge API 
  version: '1.0' 
  description: > 
    API responsible for responding to user input and communicating with Goophr 
    Librarian. 
paths: 
  /feeder: 
    post: 
      description: | 
        Register new document to be indexed. 
      responses: 
        '200': 
          description: | 
            Request was successfully completed. 
          content: 
            application/json: 
              schema: 
                $ref: '#/components/schemas/response' 
        '400': 
          description: > 
            Request was not processed because payload was incomplete or 
            incorrect. 
          content: 
            application/json: 
              schema: 
                $ref: '#/components/schemas/response' 
      requestBody: 
        content: 
          application/json: 
            schema: 
              $ref: '#/components/schemas/document' 
        required: true 
  /query: 
    post: 
      description: | 
        Search query 
      responses: 
        '200': 
          description: | 
            Response consists of links to document 
          content: 
            application/json: 
              schema: 
                type: array 
                items: 
                  $ref: '#/components/schemas/document' 
      requestBody: 
        content: 
          application/json: 
            schema: 
              type: array 
              items: 
                type: string 
        required: true 
components: 
  schemas: 
    response: 
      type: object 
      properties: 
        code: 
          type: integer 
          description: Status code to send in response 
        msg: 
          type: string 
          description: Message to send in response 
    document: 
      type: object 
      required: 
        - title 
        - link 
      properties: 
        title: 
          type: string 
          description: Title of the document 
        link: 
          type: string 
          description: Link to the document

With the help of the API description, the preceding OpenAPI definition should be self-explanatory. Details regarding the OpenAPI specification can be found at https://swagger.io/specification/. We can use tools provided by Swagger (https://editor.swagger.io/) to get a better visual representation of our API definition.

The following is the screenshot of the Goophr Concierge OpenAPI as viewed in Swagger Editor: