当前位置:网站首页>Introduction to OpenAPI specification

Introduction to OpenAPI specification

2021-05-04 14:03:18 Jiedao jdon

When I don't write articles , I work for a large software company , We have a lot of engineering teams , All of these teams are complex , Specific elements of a multifunctional and highly available business platform contribute . We chose API-First Methods to accelerate development and enhance collaboration between domains .

because API It's crucial to the way our software works , So record our API To make sure we're big IT It's important that everyone in the organization understands what's going on , That's what we use OpenAPI To help record API The reason for the norm .

In this paper , I will introduce you OpenAPI Normative and API-First Development principles .

OpenAPI standard

OpenAPI Norms start with Swagger standard , after Reverb Technologies and SmartBear And so on the company many years development ,OpenAPI The plan has the specification ( After the donation ),OpenAPI Initiative stay GitHub Community driven specifications on hosting .

Specification is a language independent format , Used to describe RESTful Web service , The application can interpret the generated file , So that the code can be generated 、 Generate documents and create simulation applications based on the services they describe .

What is? API Give priority to the development of ?

The evolution of applications to the cloud environment provides opportunities for better integration of services and increased code reuse , Just have an interface , And then through the interface , Applications of other services can interact with your applications , It's about opening up your functions to others , however , Development API But it's not supposed to be open after development .

API Documentation should be the basis for building applications , This is exactly the principle API-First(API first ) The whole content of development , You need to design and create documents that describe the interaction between the new service and the outside world , Once these interactions are established , You can develop code logic to support these interactions . Let's look at the benefits of this approach .

API-First How to benefit your organization

When your organization starts from API At the beginning of the document , This allows teams to start interacting with each other faster in the development process .API A document is a contract between an application and the people who use it .

In house development can be done in API Behind the contract , Without interfering with the efforts of the people who use it , Teams planning to use your app can use API​​ Specification to learn how to interact with your application , Even before development . They can also use this document to create virtual services for testing their applications .

OpenAPI Analysis of documents

The current version of the specification is 3.0.1 edition , And in OpenAPI GitHub There are detailed records in the repository . however , If you are like me , I prefer to see an example of norms , Instead of describing the specific technical details of every possible part through a description document .

Let's look at a description service API Simple API file , It allows users to create , modify , Retrieve and delete user preferences . You can go to SwaggerHub View this in its entirety on API .

OpenAPI A document has three required parts or objects :

1. openapi - OpenAPI The semantic version number of the specification version

2. info - of API Metadata

3. paths - API Available paths and operations for

You can include other objects as needed . Other objects include security , The server , Tags and components .

openapi: 3.0.1
info:
 version: "1.0.0"
 title:  User guidance API
 description:  This is a creation that supports user settings , modify , Search and delete .
<p>

openapi Object declares the version of the specification used for the document . This version is crucial for users to understand the structure of the document , what's more , For any tool that might acquire documents or create virtual services for validation purposes ,info Object provides information about API The basic information of itself . Title and version are required fields , We can choose to include other information , For example, description , Contact and license information .

Path object

paths The path object is API The core of the document . This object details the path to interact with the application , The available methods and details of what these interactions contain . The object includes request parameters and expected results :

paths:
 /preference:
   get:
     summary:  according to ID Discover user settings 
     description:  Return to user settings 
     operationId: getPreferenceById
     parameters:
     - name: id
       in: query
       description:  This returns a user set ID
       required: true
       schema:
         type: string
     responses:
       '200':
         description:  The request is successful 
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/Preference'
       '400':
         description:  Invalid  ID
       '404':
         description:  User settings not found 
<p>

The excerpt above describes pressing ID Retrieve user set GET Request path , Most of these attributes are self-evident . It is worth noting that HTTP 200 Patterns of response .$ ref Properties refer to objects elsewhere in the file , It's a description for multiple paths :

#/components/schemas/Preference The structure is as follows :

components:
 schemas:
   Preference:
     type: object
     required:
     - userId
     - preferenceName
     - status
     properties:
       userId:
         type: string
         format: uuid
       preferenceName:
         type: string
       preferenceValue:
         type: string
       status:
         type: string
         description: Preference Status
         enum:
         - test
         - enabled
         - disabled
         - delete
<p>

Define the component in another place and reference it , This way we can reuse the same definition and make our OpenAPI Contracts are easier to manage .

stay swaggerhub Have an online editor to experience .


Getting Started with the OpenAPI Specification · S

版权声明
本文为[Jiedao jdon]所创,转载请带上原文链接,感谢
https://chowdera.com/2021/05/20210504135746383n.html

随机推荐