Articleswift-openapi-generator 1.5.0swift-openapi-generator

Exploring an OpenAPI document

This tutorial covers the basics of the OpenAPI specification and guides you through writing an OpenAPI document that describes a service API. We’ll use a fictitious service that returns a personalized greeting.

ExploreOpenAPI.tutorial

% curl 'localhost:8080/api/greet?name=Jane'
{
  "message" : "Hello, Jane"
}

Explore the GreetingService OpenAPI document

The OpenAPI document in openapi.yaml provides a structured declaration of the service.

Every OpenAPI document needs to declare its format version using the openapi key. Use the version 3.1.0 for this document.
```
openapi.yaml
```
```
openapi: '3.1.0'
```
exploring-openapi.openapi.0.yaml
The info section contains the service name, GreetingService, and declares the API version.
```
openapi.yaml
```
```
openapi: '3.1.0'
info:
  title: GreetingService
  version: 1.0.0
```
exploring-openapi.openapi.1.yaml

The servers section declares a list of existing service URLs.

openapi.yaml

openapi: '3.1.0'
info:
  title: GreetingService
  version: 1.0.0
servers:
  - url: https://example.com/api
    description: Example service deployment.

exploring-openapi.openapi.2.yaml

The paths section contains the list of paths and HTTP operations that make up the API.
There is a single path /greet on which the server will handle HTTP GET requests. Provide an operationId to give code generators a useful hint of what to call the generated method.
```
openapi.yaml
```
```
openapi: '3.1.0'
info:
  title: GreetingService
  version: 1.0.0
servers:
  - url: https://example.com/api
    description: Example service deployment.
paths:
  /greet:
    get:
      operationId: getGreeting
```
exploring-openapi.openapi.3.yaml

Document the optional query parameter that provides the name of the person to be greeted in the parameters section.

openapi.yaml

openapi: '3.1.0'
info:
  title: GreetingService
  version: 1.0.0
servers:
  - url: https://example.com/api
    description: Example service deployment.
paths:
  /greet:
    get:
      operationId: getGreeting
      parameters:
      - name: name
        required: false
        in: query
        description: The name used in the returned greeting.
        schema:
          type: string

exploring-openapi.openapi.4.yaml

The different responses are also documented. In this case, the server will always return the HTTP status code 200.

openapi.yaml

openapi: '3.1.0'
info:
  title: GreetingService
  version: 1.0.0
servers:
  - url: https://example.com/api
    description: Example service deployment.
paths:
  /greet:
    get:
      operationId: getGreeting
      parameters:
      - name: name
        required: false
        in: query
        description: The name used in the returned greeting.
        schema:
          type: string
      responses:
        '200':
          description: A success response with a greeting.

exploring-openapi.openapi.5.yaml

In the response, describe the structure of the JSON body using JSON Schema.

Define the reusable type in the #/components/schemas section, give it the name Greeting, and refer to it from the response definition of the JSON response body.

openapi.yaml

openapi: '3.1.0'
info:
  title: GreetingService
  version: 1.0.0
servers:
  - url: https://example.com/api
    description: Example service deployment.
paths:
  /greet:
    get:
      operationId: getGreeting
      parameters:
      - name: name
        required: false
        in: query
        description: The name used in the returned greeting.
        schema:
          type: string
      responses:
        '200':
          description: A success response with a greeting.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Greeting'
components:
  schemas:
    Greeting:
      type: object
      properties:
        message:
          type: string
      required:
        - message

exploring-openapi.openapi.6.yaml

There you go! This is a simple, yet complete, example of an OpenAPI document that describes the API of GreetingService.

openapi.yaml

openapi: '3.1.0'
info:
  title: GreetingService
  version: 1.0.0
servers:
  - url: https://example.com/api
    description: Example service deployment.
paths:
  /greet:
    get:
      operationId: getGreeting
      parameters:
      - name: name
        required: false
        in: query
        description: The name used in the returned greeting.
        schema:
          type: string
      responses:
        '200':
          description: A success response with a greeting.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Greeting'
components:
  schemas:
    Greeting:
      type: object
      properties:
        message:
          type: string
      required:
        - message

exploring-openapi.openapi.7.yaml