Swagger from entry to abandonment

How to write API documentation based on OpenAPI specification

Introduction

Swagger
Swagger is a simple but powerful API expression tool. Wide variety of languages supported
Using Swagger to generate APIs, we can get interactive documentation, SDKs that automatically generate code, and API discovery features
OpenAPI Specification
The OpenAPI specification is a project of the Linux Foundation that attempts to define a language for describing API formats or API definitions to standardize the development process of RESTful services
OpenAPI can help us describe the basic information of an API:
- General description about the API
- Available paths
- Available operations on each path
- Input and output formats for each operation
API definition languages such as the OpenAPI specification can express APIs more simply and quickly, especially in the API design stage.
How to write API documentation
The editor adopts online editing: https://editor.swagger.io/#
``YAML swagger: "2.0" info: description: "This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key \special-key` to test the authorization filters."
version: "1.0.0"
title: "Swagger Petstore"
termsOfService: "http://swagger.io/terms/"
contact:
email: "[email protected]"
license:
name: "Apache 2.0"
url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "petstore.swagger.io"
basePath: "/v2"
tags:
- name: "pet"
  description: "Everything about your Pets"
  externalDocs:
  description: "Find out more"
  url: "http://swagger.io"
- name: "store"
  description: "Access to Petstore orders"
- name: "user"
  description: "Operations about user"
  externalDocs:
  description: "Find out more about our store"
  url: "http://swagger.io"
  schemes:
- "http"
  paths:
  /pet:
  post:
  tags:
  - "pet"
  summary: "Add a new pet to the store"
  description: ""
  operationId: "addPet"
  consumes:
  - "application/json"
  - "application/xml"
  produces:
  - "application/xml"
  - "application/json"
  parameters:
  - in: "body"
  name: "body"
  description: "Pet object that needs to be added to the store"
  required: true
  schema:
  $ref: "#/definitions/Pet"
  responses:
  405:
  description: "Invalid input"
  security:
  - petstore_auth:
  - "write:pets"
  - "read:pets"

from scratch

swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation

schemes: 
- https
host: simple.api
basePath: /openapi101
paths:
{}

The display interface is as follows:
First, declare the version of the OpenAPI specification through the swagger attribute
Then you need to explain the relevant information of the API document, such as API document version, API document name, description information, etc.
Finally, as a webURL, a very important piece of information is the root URL used by consumers, which can be described using the protocol http or https, hostname, and root path:
YAML schemes: - https host: simple.api basePath: /openapi101
The next step is to write the operation of the API, through paths, but there is no writing here but the location is occupied by the {} object

swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation

schemes: 
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
    get:
    summary: Get some persons
    description: Returns a list containing all persons
    responses:
        200:
            description: A list of Person
            schema:
                type: array
                items:
                    required: 
                        - username
                    properties:
                        firstname:
                            type: string
                        lastname:
                            type: string
                        username:
                            type: string

In the above code, the following actions are done:
1. Added /persons path to access a set of user information
2. The HTTP method get is added to the path, and there are also some simple description information summary and description
3. Define the response type responses, and add HTTP status code 200 to the response type
4. The response content is defined: the specific return content is clearly described by the schema attribute in the response message. Through the type attribute, it can be known that a group of user information is an array of user information, and each array element is a user object, which contains three attributes of type string, of which username must be provided (required)
Define request parameters

paths:
/persons:
    get:
    summary: Get some persons
    description: Returns a list containing all persons
    parameters: 
        -   name: pageSize
            in: query
            description: Number of persons returned
            type: integer
        -   name: pageNumber
            in: query
            description: Page number
            type: integer

First add a parameters property to the get method
In the parameter list, the integer parameters of two parameters pageSize and pageNumber are added, and there is a brief description
define path parameters

swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation

schemes: 
- https
host: simple.api
basePath: /openapi101
paths:
/persons/{username}:
    get:
    summary: Get some persons
    description: Returns a list containing all persons
    parameters: 
        -   name: username
            in: path
            required: true
            description: The person's username
            type: string

    responses:
        200:
        description: A list of Person
        schema:
            type: array
            items:
                required: 
                    - username
                properties:
                    firstname:
                        type: string
                    lastname:
                        type: string
                    username:
                        type: string

The difference between path parameters, request parameters, and message parameters is that the values of the in attributes are different, which are path, query, body, and so on. At the same time, the type of the parameter can be defined using type or schema. For example, the message body parameters are as follows:

swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation

schemes: 
- https
host: simple.api
basePath: /openapi101
paths:
    /persons:
        post:
        summary: Creates a person
        description: Adds a new person to the persons list
        parameters: 
            -   name: person
                in: body
                description: The person to create
                schema:
                    required: 
                    - username
                    properties:
                        firstname:
                            type: string
                        lastname:
                            type: string
                        username:
                            type: string
        responses:
            200:
            description: OK

If it is a single parameter, it can be defined using type such as integer, string, array, etc., and if it is a parameter of json type, it needs to be defined using the schema class.
Define the corresponding message

response:
    204:
        description:Persons successfully created
    400:
        description:Persons couldn't have been created

Simplified data model
Reusable objects are defined by using definitions. as follows:

swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation

schemes: 
- https
host: simple.api
basePath: /openapi101
paths:
/persons:
    post:
    summary: Creates a person
    description: Adds a new person to the persons list
    parameters: 
        -   name: person
            in: body
            description: The person to create
            schema:
                $ref: '#/definitions/Person'
    responses:
        200:
        description: OK
        schema:
            $ref: "#/definitions/Person"

definitions:
    Person:
        required:
            - username
        properties:
            firstname:
                type: string
            lastname: 
                type: string
            username:
                type: string

Define reusable parameters

swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API documentation

schemes: 
- https
host: simple.api
basePath: /openapi101
paths:
    /persons/{username}:
        get:
            parameters: 
                - $ref: '#/parameters/username'

            responses:
                200:
                description: fsafsf

parameters:
    username:
        name: username
        in: path
        required: true
        description: The person's username
        type: string

Advanced Definition

String length and format

-   name: username
    in: path
    required: true
    description: fasfsa
    type: string
    pattern: "[a-z0-9]{8,64}"
    minLength: 8
    maxLength: 64

date and time

parameters: 
    - name: dateofBirth
      in: query
      description: fasfsaf
      type: string
      format: date

enum type

code:
    type: string
    enum: 
        - DBERR
        - NTERR
        - UNERR

Advanced parameters
the media type of the parameter
Add below the root node of the document:

produces:
    - text/xml
consumes:
    - application/json
    - application/xml

Advanced Response Message
To define a corresponding message without a message body, just write the response status and description

responses:
    '204':
        description: Person successfully created

Similar to the request message, the required parameters are identified by required

Person:
    required:
        - username
    properties:
        firstname:
            type: string
        lastname: 
            type: string
        username: 
            type: string

Category labels
tags: - Persons

Swagger from entry to abandonment

How to write API documentation based on OpenAPI specification

Introduction

from scratch

Advanced Definition

Guess you like