SpringDoc OpenAPI YAML Çıktısı

Giriş

OpenAPI çıktıyı yaml olarak görmek için şu adrese gideriz 

http://localhost:8080/v3/api-docs.yaml

Çıktı Bileşenleri

1. Metadata Sections

2. Servers and Tags Sections

3. Components Section

4. Path Section

1. Metadata Sections

Açıklaması şöyle

1. openapi — The openapi section indicates the version of OAS used. For example, “3.0.3” signifies major version 3 with patch version 3.

2. info — The info section contains metadata about the API, such as its title, description, terms of service, contact details, license information, and version.

3. externalDocs — The externalDocs section provides a link to extended documentation related to the API, including a description and URL.

Örnek

Şöyledir

openapi: 3.0.3

info:
  title: Sample Ecommerce App API
  description: |
    This is a sample ecommerce app API
  termsOfService: https://github.com/someUserId/someProject/blob/main/LICENSE
  contact:
    name: Ecommerce Support
    url: https://www.ecomm.com
    email: support@ecomm.com
  license:
    name: MIT
    url: https://github.com/someUserId/someProject/blob/main/LICENSE
  version: 1.0.0

externalDocs:
  description: Any document link you want to generate along with API.
  url: http://swagger.io

2. Servers and Tags Sections

Açıklaması şöyle

4. servers — The servers section lists the servers hosting the API, facilitating interactive documentation through tools like Swagger UI.

5. tags — The tags section groups operations related to specific resources, allowing for better organization and grouping in generated code.

Örnek

Şöyledir

servers:
  - url: https://ecommerce.swagger.io/v2

tags:
  - name: cart
    description: Everything about cart
    externalDocs:
      description: Find out more (extra document link)
      url: http://swagger.io
  - name: order
    description: Operation about orders

3. Components Section

Açıklaması şöyle

The components section is used to define models and reusable components, such as request bodies, responses, and schemas. 

Örnek

Şöyledir

components:
  schemas:
    Cart:
      description: Shopping Cart of the user
      type: object
      properties:
        customerId:
          description: Id of the customer who possesses the cart
          type: string
        items:
          description: Collection of items in cart.
          type: array
          items:
            $ref: '#/components/schemas/Item'

4. Path Section

Açıklaması şöyle

The paths section defines API endpoints, including the URI, HTTP methods, parameters, responses, and more.

Örnek

Şöyledir

paths:
  /api/v1/carts/{customerId}:
    get:
      tags:
        - cart
      summary: Returns the shopping cart
      description: Returns the shopping cart of a given customer
      operationId: getCartByCustomerId
      parameters:
        - name: customerId
          in: path
          description: Customer Identifier
          required: true
          schema:
            type: string
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Cart'
        404:
          description: Given customer ID doesn't exist
          content: {}