SwaggerAPI + .NET

Projekti installimise ja API-ga töötamise juhend

1. Mis on API?

API (Application Programming Interface) — see on liides, mille kaudu üks programm suhtleb teisega. Veebi API-sid kasutatakse sageli andmete vahetamiseks veebirakenduste ja serveri vahel. Need võimaldavad kliendirakendustel (nt veebisaidid või mobiilirakendused) saata päringuid ja saada vastuseid serveritelt, kus on salvestatud äriloogikat või andmeid.

Swagger on avatud lähtekoodiga raamistik, mis aitab arendajatel luua, dokumenteerida ja testida API-sid. See võimaldab automaatselt genereerida dokumentatsiooni teie API-le, samuti pakkuda lihtsat ja kasutajasõbralikku liidest, kus kasutajad saavad API-d testida ilma täiendavate tööriistadeta. Swagger aitab API-de loojatel ja kasutajatel mõista, kuidas API töötab, milliseid ressursse ja meetodeid saab kasutada ning milliseid andmeid tuleb edastada ja millist vormingut vastusena oodata.

Peamised omadused:

  1. Interaktiivne dokumentatsioon: Swaggeri dokumentatsiooni kaudu on võimalik vaadata kõiki API endpointe ja neid otse testida.
  2. Automaatselt genereeritud dokumentatsioon: Swagger loeb teie API koodi ja genereerib dokumentatsiooni automaatselt, muutes selle alati ajakohaseks.
  3. Testimine ja silumine: Swaggeri UI võimaldab teil kiiresti API-d testida ja saada vastuseid otse veebiliideses.
  4. API-skeemid ja kirjeldused: Kasutades OpenAPI Spetsifikatsiooni, Swagger kirjeldab kõiki API toiminguid ja vajalikke andmeformaate.

Swagger on suurepärane tööriist nii arendajatele kui ka inimestele, kes tarbivad API-sid, kuna see pakub selget ja struktureeritud viisi mõista, kuidas API töötab.

1. Loo uus ASP.NET Core projekt

  • Samm 1: Ava Visual Studio.
  • Samm 2: Vali “Create a new project” ja vali ASP.NET Core Web API.
  • Samm 3: Pane oma projektile nimi (näiteks “KasutajaApi”) ja vajuta “Create”.

2. Loo mudel (Model)

Mudeli klass kirjeldab andmete struktuuri, näiteks kasutaja andmeid.

3. Loo API kontroller (Controller)

Kontroller määrab, kuidas API teenindab päringuid (GET, POST, DELETE jne).

4. Käivita API

  • Samm 1: Vajuta F5, et käivitada projekt. See avab sinu API brauseris.
  • Samm 2: Testi päringuid Postmanis või brauseri kaudu:
    • /https://localhost:7198/swagger/index.html
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;

namespace BohatyrovAPI.Controllers
{
    [Route("[controller]")]
    [ApiController]
    public class PrimitiividController : ControllerBase
    {

        // GET: primitiivid/hello-world
        [HttpGet("hello-world")]
        public string HelloWorld()
        {
            return "Hello world at " + DateTime.Now;
        }

        // GET: primitiivid/hello-variable/mari
        [HttpGet("hello-variable/{nimi}")]
        public string HelloVariable(string nimi)
        {
            return "Hello " + nimi;
        }

        // GET: primitiivid/add/5/6
        [HttpGet("add/{nr1}/{nr2}")]
        public int AddNumbers(int nr1, int nr2)
        {
            return nr1 + nr2;
        }

        // GET: primitiivid/multiply/5/6
        [HttpGet("multiply/{nr1}/{nr2}")]
        public int Multiply(int nr1, int nr2)
        {
            return nr1 * nr2;
        }



        // GET: primitiivid/do-logs/5
        [HttpGet("do-logs/{arv}")]
        public void DoLogs(int arv)
        {
            for (int i = 0; i < arv; i++)
            {
                Console.WriteLine("See on logi nr " + i);
            }
        }
        Random rnd = new Random();
        [HttpGet("random")]

        public int Random()
        {
            return rnd.Next();
        }

        [HttpGet("birthday/{yearOfBirth}")]

        public string Birthday(int yearOfBirth)
        {

            DateTime currentDate = DateTime.Now;

            int age = currentDate.Year - yearOfBirth;

       

            return $"oled nii või naa aastat vana {age}, olenevalt kas sellel aastal on sünnipäev juba olnud";
        }

        // GET: primitiivid/describe/10/20
        [HttpGet("describe/{nr1}/{nr2}")]
        public string DescribeNumbers(int nr1, int nr2)
        {
            return $"Lauses on kaks arvu: {nr1} ja {nr2}.";
        }
    }
}

Tagasi hellow maailma kuupäevaga kohe

        // GET: primitiivid/hello-world
        [HttpGet("hello-world")]
        public string HelloWorld()
        {
            return "Hello world at " + DateTime.Now;
        }

Tagastab stringi „Tere“ ja teie nime

        // GET: primitiivid/hello-variable/mari
        [HttpGet("hello-variable/{nimi}")]
        public string HelloVariable(string nimi)
        {
            return "Hello " + nimi;
        }

Hangi juhuslik number

      Random rnd = new Random();
      [HttpGet("random")]

      public int Random()
      {
          return rnd.Next();
      }

2 numbri summa

       // GET: primitiivid/add/5/6
       [HttpGet("add/{nr1}/{nr2}")]
       public int AddNumbers(int nr1, int nr2)
       {
           return nr1 + nr2;
       }

2 arvu korrutamine

      // GET: primitiivid/multiply/5/6
      [HttpGet("multiply/{nr1}/{nr2}")]
      public int Multiply(int nr1, int nr2)
      {
          return nr1 * nr2;
      }

Tagasiarvestus terminalis

        // GET: primitiivid/do-logs/5
        [HttpGet("do-logs/{arv}")]
        public void DoLogs(int arv)
        {
            for (int i = 0; i < arv; i++)
            {
                Console.WriteLine("See on logi nr " + i);
            }
        }

Lugege oma vanust oma sünnikuupäeva järgi

        [HttpGet("birthday/{yearOfBirth}")]

        public string Birthday(int yearOfBirth)
        {

            DateTime currentDate = DateTime.Now;

            int age = currentDate.Year - yearOfBirth;

       

            return $"oled nii või naa aastat vana {age}, olenevalt kas sellel aastal on sünnipäev juba olnud";
        }

Arvutan, kui vana kasutaja on, olenevalt tema sünniaastast

Kirjeldage 2 numbrit lausega

        // GET: primitiivid/describe/10/20
        [HttpGet("describe/{nr1}/{nr2}")]
        public string DescribeNumbers(int nr1, int nr2)
        {
            return $"Lauses on kaks arvu: {nr1} ja {nr2}.";
        }

Kui see on string, siis tagastab ta vea staatusega 400

Toode

luua Toode klass ja sellesse konstruktor

namespace BohatyrovAPI.Models
{
    public class Toode
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public double Price { get; set; }
        public bool IsActive { get; set; }

        public Toode(int id, string name, double price, bool isActive)
        {
            Id = id;
            Name = name;
            Price = price;
            IsActive = isActive;
        }
    }
}

Teeme uue kontrolleri ja kuulutame seal välja uue toote

    [Route("[controller]")]
    [ApiController]
    public class ToodeController : ControllerBase
    {
        private static Toode _toode = new Toode(1, "Koola", 1.5, true);

        // GET: toode
        [HttpGet]
        public Toode GetToode()
        {
            return _toode;
        }
    }

Lisa +1 toote maksumusele

       // GET: toode/suurenda-hinda
        [HttpGet("suurenda-hinda")]
        public Toode SuurendaHinda()
        {
            _toode.Price = _toode.Price + 1;
            return _toode;
        }

Suurenda toote maksumust +1 võrra

Tooted

using BohatyrovAPI.Models;
using Microsoft.AspNetCore.Mvc;

namespace BohatyrovAPI.Controllers
{
    [Route("[controller]")]
    [ApiController]
    public class TootedController : ControllerBase
    {
        private static List<Toode> _tooted = new()
        {
            new Toode(1,"Koola", 1.5, true),
            new Toode(2,"Fanta", 1.0, false),
            new Toode(3,"Sprite", 1.7, true),
            new Toode(4,"Vichy", 2.0, true),
            new Toode(5,"Vitamin well", 2.5, true)
        };

        // GET https://localhost:7198/tooted
        [HttpGet]
        public List<Toode> Get()
        {
            return _tooted;
        }

        // DELETE https://localhost:7198/tooted/kustuta/0
        [HttpDelete("kustuta/{index}")]
        public List<Toode> Delete(int index)
        {
            _tooted.RemoveAt(index);
            return _tooted;
        }

        [HttpDelete("kustuta2/{index}")]
        public string Delete2(int index)
        {
            _tooted.RemoveAt(index);
            return "Kustutatud!";
        }

        // POST https://localhost:7198/tooted/lisa/1/Coca/1.5/true
        [HttpPost("lisa/{id}/{nimi}/{hind}/{aktiivne}")]
        public List<Toode> Add(int id, string nimi, double hind, bool aktiivne)
        {
            Toode toode = new Toode(id, nimi, hind, aktiivne);
            _tooted.Add(toode);
            return _tooted;
        }

        [HttpPost("lisa2")]
        public List<Toode> Add2(int id, string nimi, double hind, bool aktiivne)
        {
            Toode toode = new Toode(id, nimi, hind, aktiivne);
            _tooted.Add(toode);
            return _tooted;
        }

        // PATCH https://localhost:7198/tooted/hind-dollaritesse/1.5
        [HttpPatch("hind-dollaritesse/{kurss}")]
        public List<Toode> UpdatePrices(double kurss)
        {
            for (int i = 0; i < _tooted.Count; i++)
            {
                _tooted[i].Price = _tooted[i].Price * kurss;
            }
            return _tooted;
        }
    }
}

GET

      // GET https://localhost:7198/tooted
      [HttpGet]
      public List&lt;Toode> Get()
      {
          return _tooted;
      }

Kustuta

    // DELETE https://localhost:7198/tooted/kustuta/0
    [HttpDelete("kustuta/{index}")]
    public List&lt;Toode> Delete(int index)
    {
        _tooted.RemoveAt(index);
        return _tooted;
    }

Kustuta 2

        [HttpDelete("kustuta2/{index}")]
        public string Delete2(int index)
        {
            _tooted.RemoveAt(index);
            return "Kustutatud!";
        }

Lisa toode

        // POST https://localhost:7198/tooted/lisa/1/Coca/1.5/true  
        [HttpPost("lisa/{id}/{nimi}/{hind}/{aktiivne}")]
        public List<Toode> Add(int id, string nimi, double hind, bool aktiivne)
        {
            Toode toode = new Toode(id, nimi, hind, aktiivne);
            _tooted.Add(toode);
            return _tooted;
        }

Tooted

 public class TootedController : ControllerBase
 {
     private static List<Toode> _tooted = new()
     {
         new Toode(1,"Koola", 1.5, true),
         new Toode(2,"Fanta", 1.0, false),
         new Toode(3,"Sprite", 1.7, true),
         new Toode(4,"Vichy", 2.0, true),
         new Toode(5,"Vitamin well", 2.5, true)
     };

     // GET https://localhost:7198/tooted
     [HttpGet]
     public List<Toode> Get()
     {
         return _tooted;
     }

     // DELETE https://localhost:7198/tooted/kustuta/0
     [HttpDelete("kustuta/{index}")]
     public List<Toode> Delete(int index)
     {
         _tooted.RemoveAt(index);
         return _tooted;
     }

     [HttpDelete("kustuta2/{index}")]
     public string Delete2(int index)
     {
         _tooted.RemoveAt(index);
         return "Kustutatud!";
     }

     // POST https://localhost:7198/tooted/lisa/1/Coca/1.5/true  
     [HttpPost("lisa/{id}/{nimi}/{hind}/{aktiivne}")]
     public List<Toode> Add(int id, string nimi, double hind, bool aktiivne)
     {
         Toode toode = new Toode(id, nimi, hind, aktiivne);
         _tooted.Add(toode);
         return _tooted;
     }

     [HttpPost("lisa2")]
     public List<Toode> Add2(int id, string nimi, double hind, bool aktiivne)
     {
         Toode toode = new Toode(id, nimi, hind, aktiivne);
         _tooted.Add(toode);
         return _tooted;
     }

     // PATCH https://localhost:7198/tooted/hind-dollaritesse/1.5
     [HttpPatch("hind-dollaritesse/{kurss}")]
     public List<Toode> UpdatePrices(double kurss)
     {
         for (int i = 0; i < _tooted.Count; i++)
         {
             _tooted[i].Price = _tooted[i].Price * kurss;
         }
         return _tooted;
     }
 }

GET päring: saada nimekiri kõikidest toodetest

        // GET https://localhost:7198/tooted
        [HttpGet]
        public List<Toode> Get()
        {
            return _tooted;
        }

DELETE taotlus: elemendi kustutamine indeksi järgi

Kasutaja

Kasutaja mudel

Kasutaja mudel esindab rakenduse kasutajat. Seda kasutatakse kasutajate kohta käiva teabe salvestamiseks ja kasutajate sidumiseks toodetega paljude-mitmele suhte kaudu.

  • Mudeli atribuudid:
    • Id (int): Kasutaja unikaalne identifikaator. See on täisarvuväli, mis genereeritakse automaatselt uue kasutaja loomisel andmebaasis.
    • Kasutajanimi (string): Kasutajanimi, mida kasutatakse süsteemis kasutaja tuvastamiseks. See on stringiväli, mis sisaldab kasutajanime.
    • Parool (string): Kasutaja parool. See on stringiväli, mis salvestab kasutaja krüpteeritud parooli.
    • Eesnimi (string): Kasutaja eesnimi. See on stringiväli, mis sisaldab kasutaja tegelikku eesnime.
    • Perenimi (string): Kasutaja perekonnanimi. See on stringiväli, mis sisaldab kasutaja perekonnanime.
    • KasutajaTooted (List<KasutajaToode>): See on kollektsioon, mis esindab “palju-paljudele” suhet kasutajate ja toodete vahel. See sisaldab KasutajaToode objekte, mis kirjeldavad, millised tooted kuuluvad kasutajale. See on seos Toode mudeliga läbi KasutajaToode mudeli.
  • Konstruktor: Initsialiseerib Kasutaja objekti antud parameetritega (id, kasutajanimi, parool, eesnimi, perenimi).

Mudeli kirjeldus

namespace BohatyrovAPI.Models
{
    public class Kasutaja
    {
        public int Id { get; set; }
        public string Kasutajanimi { get; set; }
        public string Parool { get; set; }
        public string Eesnimi { get; set; }
        public string Perenimi { get; set; }

        // Suhe palju-paljudele tootega läbi KasutajaToode mudeli
        public List<KasutajaToode> KasutajaTooted { get; set; }

        // Konstruktor Kasutaja mudelile
        public Kasutaja(int id, string kasutajanimi, string parool, string eesnimi, string perenimi)
        {
            Id = id;
            Kasutajanimi = kasutajanimi;
            Parool = parool;
            Eesnimi = eesnimi;
            Perenimi = perenimi;
            KasutajaTooted = new List<KasutajaToode>(); // Seotud toodete loendi initsialiseerimine
        }
    }
}

Konstruktor

public Kasutaja(int id, string kasutajanimi, string parool, string eesnimi, string perenimi)
{
    Id = id;
    Kasutajanimi = kasutajanimi;
    Parool = parool;
    Eesnimi = eesnimi;
    Perenimi = perenimi;
    KasutajaTooted = new List<KasutajaToode>(); // Seotud toodete loendi initsialiseerimine
}

Kasutaja konstruktor võtab järgmised parameetrid:

  • id: Kasutaja unikaalne identifikaator (int).
  • kasutajanimi: Kasutajanimi (string).
  • parool: Kasutaja parool (string).
  • eesnimi: Kasutaja eesnimi (string).
  • perenimi: Kasutaja perekonnanimi (string).

Suhe “palju-paljudele”

Mudelil Kasutaja on suhe “palju-paljudele” mudeliga Toode läbi vahemudeli KasutajaToode. See suhe võimaldab ühel kasutajal olla seotud mitme tootega ja ühel tootel olla seotud mitme kasutajaga. Mudelis Kasutaja on see esindatud omadusega KasutajaTooted, mis on KasutajaToode objektide loend.

API lõpupunktid

1. GET /api/Kasutaja

Kirjeldus: Tagastab kõigi kasutajate loendi.

        // GET api/Kasutaja
        [HttpGet]
        public ActionResult<IEnumerable<Kasutaja>> GetKasutajad()
        {
            var kasutajad = _context.Kasutajad.ToList();
            return Ok(kasutajad);
        }

Vastus:

2. GET /api/Kasutaja/{id}

Kirjeldus: Tagastab konkreetse kasutaja, kelle ID on määratud URL-i kaudu.

// GET api/Kasutaja/{id}
[HttpGet("{id}")]
public ActionResult<Kasutaja> GetKasutaja(int id)
{
    var kasutaja = _context.Kasutajad.FirstOrDefault(k => k.Id == id);
    if (kasutaja == null)
    {
        return NotFound();
    }
    return Ok(kasutaja);
}

Vastus:

3. POST /api/Kasutaja

Kirjeldus: Lisab kasutaja

 // POST api/Kasutaja 
 [HttpPost]
 public ActionResult<Kasutaja> CreateKasutaja([FromBody] Kasutaja kasutaja)
 {
    
     kasutaja.Id = _context.Kasutajad.Any() ? _context.Kasutajad.Max(k => k.Id) + 1 : 1;

      
     _context.Kasutajad.Add(kasutaja);
     _context.SaveChanges();

     return CreatedAtAction(nameof(GetKasutaja), new { id = kasutaja.Id }, kasutaja);
 }

4. PUT /api/Kasutaja/{id}

Kirjeldus: Muudab kasutaja andmeid

// PUT api/Kasutaja/{id}
[HttpPut("{id}")]
public ActionResult UpdateKasutaja(int id, [FromBody] Kasutaja uuendatudKasutaja)
{
    var kasutaja = _context.Kasutajad.FirstOrDefault(k => k.Id == id);
    if (kasutaja == null)
    {
        return NotFound();
    }

    kasutaja.Kasutajanimi = uuendatudKasutaja.Kasutajanimi;
    kasutaja.Parool = uuendatudKasutaja.Parool;
    kasutaja.Eesnimi = uuendatudKasutaja.Eesnimi;
    kasutaja.Perenimi = uuendatudKasutaja.Perenimi;

    _context.SaveChanges();

    return NoContent();
}

4. DELETE /api/Kasutaja/{id}

        // DELETE api/Kasutaja/{id}
        [HttpDelete("{id}")]
        public ActionResult DeleteKasutaja(int id)
        {
            var kasutaja = _context.Kasutajad.FirstOrDefault(k => k.Id == id);
            if (kasutaja == null)
            {
                return NotFound();
            }

            _context.Kasutajad.Remove(kasutaja);
            _context.SaveChanges();
            return NoContent();
        }