Scribd Logo
Upload

Welcome to Scribd!

  • 111 views

    Open API 3.0

    Uploaded by

    DEV BENEDICT
    This document provides an overview of OpenAPI Specification including motivation for using it, software tools, basic syntax and usage, authentication and security, workflows, and example usages. It discusses how OpenAPI allows describing APIs in a human-readable format, generates code, maintains documentation, and facilitates communication between services. Tools covered include Swagger UI, Swagger Editor, and how to use Docker images for them. It also reviews YAML to JSON conversion, basic syntax including routes and models, and integrating OpenAPI in .NET and Fastify projects. Advantages are documentation, visualization, and hiding untagged routes, while disadvantages include exposure, required schema documentation, and reliance on server uptime.

    Copyright:

    © All Rights Reserved
    Download as PDF, TXT or read online from Scribd

    Open API 3.0

    Uploaded by

    DEV BENEDICT
    111 views32 pages
    This document provides an overview of OpenAPI Specification including motivation for using it, software tools, basic syntax and usage, authentication and security, workflows, and example usages. It discusses how OpenAPI allows describing APIs in a human-readable format, generates code, maintains documentation, and facilitates communication between services. Tools covered include Swagger UI, Swagger Editor, and how to use Docker images for them. It also reviews YAML to JSON conversion, basic syntax including routes and models, and integrating OpenAPI in .NET and Fastify projects. Advantages are documentation, visualization, and hiding untagged routes, while disadvantages include exposure, required schema documentation, and reliance on server uptime.

    Original Description:

    Original Title

    Open_API_3.0

    Copyright

    © © All Rights Reserved

    Available Formats

    PDF, TXT or read online from Scribd

    Did you find this document useful?

    Is this content inappropriate?

    This document provides an overview of OpenAPI Specification including motivation for using it, software tools, basic syntax and usage, authentication and security, workflows, and example usages. It discusses how OpenAPI allows describing APIs in a human-readable format, generates code, maintains documentation, and facilitates communication between services. Tools covered include Swagger UI, Swagger Editor, and how to use Docker images for them. It also reviews YAML to JSON conversion, basic syntax including routes and models, and integrating OpenAPI in .NET and Fastify projects. Advantages are documentation, visualization, and hiding untagged routes, while disadvantages include exposure, required schema documentation, and reliance on server uptime.

    Copyright:

    © All Rights Reserved
    Download as PDF, TXT or read online from Scribd
    Download as pdf or txt
    111 views32 pages

    Open API 3.0

    Uploaded by

    DEV BENEDICT
    This document provides an overview of OpenAPI Specification including motivation for using it, software tools, basic syntax and usage, authentication and security, workflows, and example usages. It discusses how OpenAPI allows describing APIs in a human-readable format, generates code, maintains documentation, and facilitates communication between services. Tools covered include Swagger UI, Swagger Editor, and how to use Docker images for them. It also reviews YAML to JSON conversion, basic syntax including routes and models, and integrating OpenAPI in .NET and Fastify projects. Advantages are documentation, visualization, and hiding untagged routes, while disadvantages include exposure, required schema documentation, and reliance on server uptime.

    Copyright:

    © All Rights Reserved
    Download as PDF, TXT or read online from Scribd
    Download as pdf or txt
    of 32

    OpenAPI Specification

    Kaiseir Josephus Noche


    Marc Benedict Lutab
    Mark Allen Agaton
    Outline

    ● Motivation for using OpenAPI


    ● Software Tools for OpenAPI
    ● Basic Syntax / Usage
    ● Authentication / Security
    ● Workflows using OpenAPI
    ● Example usage on existing projects
    ● Advantages / Disadvantages

    2
    Why OpenAPI

    3
    Why OpenAPI

    ● allows to describe APIs in a human readable format


    ● framework agnostic
    ● easily generate mock server side code or client sdks for different languages
    ● easily maintain documentations
    ● communication between services is easier

    4
    Software Tools for OpenAPI

    5
    Swagger UI

    ● tool for viewing OpenAPI files


    (both in yaml or json)
    ● hosted online at
    https://petstore.swagger.io/

    6
    Swagger UI

    ● Docker Image: https://hub.docker.com/r/swaggerapi/swagger-ui


    ○ docker pull swaggerapi/swagger-ui
    ○ docker container run -i -p 3081:80 –name swagger-ui swaggerapi/swagger-ui

    7
    Swagger Editor

    ● tool for writing OpenAPI


    definitions
    ● hosted online at
    https://editor.swagger.io/

    8
    Swagger Editor

    ● Docker Image: https://hub.docker.com/r/swaggerapi/swagger-editor


    ○ docker pull swagerapi/swagger-editor
    ○ docker container run -i -p 3080:80 –name swagger-editor swaggerapi/swagger-editor

    9
    Basic Syntax / Usage

    10
    YAML to JSON and vice versa
    YAML JSON

    11
    OpenAPI Basic Syntax

    ● Sample OpenAPI yaml files:


    ○ https://static.nowserving.ph/api/test-1.yaml
    ○ https://static.nowserving.ph/api/sample-api-
    03-23-2022.yaml
    ● To follow along use either
    ○ your local swagger-ui OR
    ○ go to https://petstore.swagger.io/ and paste
    the link of the sample OpenAPI yaml file

    Sample OpenAPI spec in swagger-ui

    12
    OpenAPI Basic Syntax

    13
    OpenAPI Basic Syntax - Adding route definition

    14
    OpenAPI Basic Syntax - POST route definition

    15
    Adding Models

    16
    Adding Authentication / Security

    17
    Basic Syntax Summary

    18
    Workflows with OpenAPI

    19
    Possible Workflows with OpenAPI

    20
    Example usages of OpenAPI

    21
    Programs / Coupons Gateway

    ● OpenAPI specification was generated using


    a .NET library called Swashbuckle
    ● Documentation is tightly integrated with the
    controller actions

    22
    Workflow of getting / sharing OpenAPI Spec from .NET

    - download swagger.json
    - convert to yaml using
    swagger-editor
    - add further documentation such as
    the servers to which the api should
    be directed
    - save to yaml to S3 / other storage
    - view yaml file using swagger-ui
    - enabled cors to be able to process
    request from swagger-ui

    23
    Programs / Coupons Gateway

    ● sample OpenAPI Spec generated


    from .NET
    ○ https://static.nowserving.ph/api
    /smd-programs-gateway-test.ya
    ml
    -

    24
    Public Directory

    ● OpenAPI yaml file


    ○ https://static.nowserving.ph/api/pu
    blic-directory-openapi.yaml

    25
    SMD Badges API

    - Swagger/OpenAPI is a plugin for Fastify


    - Seamless tagging of APIs
    - API schema is reused for documentation

    26
    SMD Badges API

    - http://nowserving.smdstaging.net:3918/documentation

    27
    Advantages / Disadvantages

    28
    Advantages

    - In Fastify, documentation is written as you write the route schemas


    - With correct server fields, can act as a POSTMAN with guided detailed schemas
    - Visually more appealing than documentation in google sheets
    - Easier way to find documentation for a particular server
    - Fastify has the option to not expose the documentation route and to hide untagged routes
    - Quickly shows possible params, querystring and body
    - Internal interfaces such as database schemas can be documented

    29
    Disadvantages

    - Documentation is exposed to everyone in the VPN


    - Not yet tested in Express
    - Will require almost perfect schema documentation
    - Will require to write schemas for servers that do not have route schemas
    - Will require to remember server urls to access documentation
    - Internal route process has to be written in paragraph form and in IDE
    - Documentation can only be accessed if server is up
    - Cannot be used by RMQ workers?

    30
    Caveats

    - Fastify-swagger must be registered before adding routes to fastify object

    31
    References

    [1] Rosenstock, L. and Ponelat, J., n.d. Designing APIs with Swagger and OpenAPI.
    (https://drive.google.com/file/d/1JPpDbJSP0cmkmio2nKXsJiPTGL2JiOSQ/view?usp=sharing)

    32

    You might also like