[Roast: Day - Auto-Cipta Pelayan API Tanpa AI

Untuk menyambungkan antara muka hadapan saya kepada pangkalan data, saya perlu mereka bentuk API untuk membenarkan aplikasi bahagian hadapan mendapatkan semula dan menghantar data. Ini akan membolehkan logik pengguna saya, seperti membuat akaun, log masuk dan keluar, dsb. Ini akan membolehkan semua logik di sekitar panggang.

Saya pernah mencipta Express API sebelum ini, tetapi kali ini saya ingin melihat sama ada saya boleh mempelajari lebih lanjut tentang Swagger dalam proses binaan.

Suite Swagger

Swagger ialah syarikat yang mereka bentuk dan menyelenggara tiga produk, Editor Swagger, CodeGen Swagger dan UI Swagger. Ketiga-tiga produk ini bekerjasama untuk menjadikan aplikasi yang mematuhi OpenAPI (dan dokumentasi) lebih mudah!

Menggunakan Kontrak

Proses menggunakan Swagger untuk mencipta API bermula dengan Editor Swagger. Alat ini membolehkan anda membuat apa yang dipanggil kontrak. Kontrak ialah dokumen YAML yang mentakrifkan perkara yang berbeza tentang aplikasi seperti nama, laluan yang akan dikendalikannya dan sebagainya.

YAML lwn. JSON

Jika anda tidak pernah menggunakan YAML sebelum ini, ia adalah bahasa penanda berasaskan objek yang lebih longgar yang mempunyai beberapa persamaan dengan JSON, tetapi lebih mudah untuk menaip dengan cepat. Berikut ialah contoh kandungan yang sama dalam JSON dan kemudian dalam YAML:

// JSON Example
{
  "name": "ThisApp",
  "description": "An example of data.",
  "list": [
    "option1",
    "option2",
    "option3"
  ],
  "object": {
    "key": "value"
  }
}

# YAML Example
name: ThisApp
description: An example of data.
list:
  - option1
  - option2
  - option3
object:
  key: value

Perhatikan bahawa YAML, walaupun masih boleh dibaca mesin, adalah sedikit lebih mudah untuk dibaca oleh manusia juga, menjadikannya bahasa penanda yang bagus untuk spesifikasi ini.

Menentukan Spesifikasi API

Menggunakan Editor Swagger dan mengikuti OAS, anda boleh menulis semua yang biasa anda atur ke dalam API.

Di peringkat teratas, anda akan menentukan spesifik aplikasi:

openapi: 3.0.3
info:
  title: Roast - Know Your Home Roasts
  description: # This will appear in the API UI
  version: 1.0.0
servers:
  - url: # A url to one or more servers here
tags:  These are groups of paths
  - name: user
    description: Operations for your user
  - name: roast
    description: Access to roasts
paths:
  # Define all of your paths in this object
components:
  # Define reusable pieces of code here

Keajaiban CodeEditor menjadi nyata apabila anda mula menentukan laluan. Ambil laluan berikut yang saya takrifkan untuk mendapatkan satu panggang mengikut id.

# ... contract information
paths:
  # ... users paths, etc.
  /roasts/{roastId}:
    get:
      tags:
        - roast
      summary: Get roast by id
      description: Must include a valid roast id
      parameters:
        - $ref: '#/components/parameters/roastIdParam'
      responses:
        '200': 
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Roast"
        '400':
          $ref: '#/components/responses/Invalid'
        '404':
          $ref: '#/components/responses/NotFound'

Mari kita pecahkan objek ini. Pertama, ia dipanggil /roasts/{roastId}. Ini bermakna kami mentakrifkan kelakuan yang dijangkakan pelayan apabila permintaan dihantar ke laluan ini. Apa yang berlaku di bawah itu?

• get: Ini memberitahu alatan Swagger bahawa kami ingin mentakrifkan titik akhir permintaan GET untuk laluan ini, maklumat selebihnya tentang permintaan GET akan berada di dalam objek itu.
• tag: Ini ialah sifat pilihan titik akhir, tetapi ia berguna dalam UI, kerana ia membolehkan anda mengumpulkan titik akhir anda dalam dokumentasi anda.
• ringkasan: dan penerangan: Dalam pemaparan pada skrin UI Swagger, anda akan melihat kedua-dua medan ini di tempat yang berbeza. Ringkasan memberikan penjelasan pantas tentang kefungsian titik akhir dan Penerangan memberikan butiran tambahan.
• parameter: Sifat get: ini adalah tempat parameter laluan boleh ditentukan. Anda boleh memasukkan maklumat seperti, sama ada parameter diperlukan atau tidak dan jenis data yang diharapkan.
• respons: Inilah daging dan kentang. Dikenal pasti sebagai rentetan kod status, setiap respons yang sah daripada titik akhir boleh disenaraikan di sini untuk tujuan dokumentasi dan penjanaan kod.

Kekal KERING dengan Komponen

Membangunkan kontrak seperti ini, anda mungkin akan mendapati diri anda menaip perkara yang sama berulang kali. Dan anda mungkin tahu sebagai pengaturcara, bahawa kami mahu mengikuti prinsip KERING: "Jangan Ulangi Sendiri." Contohnya, apabila mentakrifkan badan permintaan yang diperlukan, akan terdapat beberapa titik akhir yang mungkin memerlukan objek yang sama.

Di sinilah komponen masuk. Untuk contoh ini, anda boleh mentakrifkan skema dan kemudian merujuk skema itu di mana-mana dalam kontrak menggunakan $ref: .

Jadi, di bahagian bawah kontrak saya, saya mempunyai komponen: objek.

components:
  schemas:
    Roast: # An arbitrary name to identify the schema
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        ## Include all other properties

Objek komponen ini, mengandungi skema yang dipanggil Roast , jadi sekarang, jika saya perlu menentukan bahawa objek ini perlu dihantar dalam permintaan, katakan, dalam permintaan POST ke /roast untuk menambah panggang baharu. Saya boleh merujuk objek dengan cara ini:

/roast:
  post:
    # additional specifications
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Roast'

Anda juga boleh melakukan ini dalam menentukan parameter anda dan banyak bahagian lain yang berulang pada spesifikasi anda!

Dokumentasi Automatik

Semasa anda menaip dalam Editor Swagger anda, sepanjang masa, UI Swagger sentiasa dikemas kini dalam tetingkap di sebelah kanan anda. Swagger UI sedang mengemas kini perkara yang akan menjadi dokumentasi API anda! Ini bermakna anda tidak perlu kembali kemudian dan menulis dokumentasi sendiri.

Bahagian terbaik tentang ini, ialah ia akan disampaikan bersama aplikasi anda (selagi anda menggunakan CodeGen untuk menciptanya).

Let Swagger Code Your API Too!

Once you feel like your API is up to spec, you can have a working server in 17 different languages/frameworks in seconds! Just click Generate Server, and select your flavor and CodeGen reads your OAS spec and downloads a server.

In Node, your code comes out in a few different directories.

generated-server/
|-- api/
|-- controllers/
|-- service/
|-- utils/
|-- README.md
|-- index.js
|-- package.json

The api directory contains your OpenAPI spec. The controllers directory contains a file for each of your path groups, with exported functions specifically for handling the unique paths and operations of your application. The service directory, is where you will hook these operations up to your database and perform the business logic of the application, and utils contains functions that help read and write data.

Your server will actually live in index.js.

Is It Really That Easy?

Yes! Well, sort of.

CodeGen does in fact make a working server for you, but it's still up to you to hook up the database and design the logic of the application! But, it gives you a complete and organized skeleton that you can work in!

Here's an example of the code that it output for my POST request to /roasts .

// controllers/Roast.js
// ...
module.exports.addRoast = function addRoast (req, res, next, body) {
  Roast.addRoast(body)
    .then(function (response) {
      utils.writeJson(res, response);
    })
    .catch(function (response) {
      utils.writeJson(res, response);
    });
};

// service/RoastService.js
// ...
exports.addRoast = function(body) {
  return new Promise(function(resolve, reject) {
    var examples = {};
    examples['application/json'] = {
  "notes" : "Doesn't taste as good as last time... I wonder if the weather is making the beans roast faster now that it's warmer",
  "heatLevel" : "Med",
  "origin" : "Ethiopian",
  // ...
  "id" : 10,
};
    if (Object.keys(examples).length > 0) {
      resolve(examples[Object.keys(examples)[0]]);
    } else {
      resolve();
    }
  });
}

The above code was entirely generated by Swagger CodeGen. However, it won't actually add a roast object anywhere. This is creating a mock object and sending it back. But, after hooking up a Postgres database, and creating queries with this logic inside the service, the API will be fully operational!

Would You Use It?

I loved working with Swagger on this API, it was the first time that I committed to learning some of the intricacies of OAS to generate the server. The only rub that I have with it is that the docs are not formatted the best, and they can be hard to navigate searching for what you want to add to the server.

But, once you're familiar with OAS, this tool can save a ton of time. Not only do you have extremely thorough documentation when you're done, but you can treat the generated code as a to-do list of the functions and logic that you need to implement as you build!

Would you give it a try?

---

Check Out the Project

If you want to keep up with the changes, fork and run locally, or even suggest code changes, here’s a link to the GitHub repo!

https://github.com/nmiller15/roast

The frontend application is currently deployed on Netlify! If you want to mess around with some features and see it in action, view it on a mobile device below.

https://knowyourhomeroast.netlify.app

Note: This deployment has no backend api, so accounts and roasts are not actually saved anywhere between sessions.

Atas ialah kandungan terperinci [Roast: Day - Auto-Cipta Pelayan API Tanpa AI. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!