PricingLoginStart free
Spring Boot 4 -mikropalvelut ja REST-sovellusliittymät · Oppitunti

OpenAPI-määrityksen mukauttaminen

Lisätkää metatietoja, palvelimia ja suojausmalleja.

Oppitunti 3/413 vaihetta

OpenAPI-määrityksen mukauttaminen on ilmainen Spring Boot 4 -mikropalvelut ja REST-sovellusliittymät-oppitunti CoddyKitissä. Tämä on oppitunti 3/4. Voit lukea koko oppitunnin alta ilmaiseksi ja harjoitella sen jälkeen käytännössä selaimessa sisäänrakennetulla koodieditorilla ja ympäri vuorokauden käytettävissä olevan tekoälytuutorin avulla. Oppitunti kuuluu Spring Boot 4 -mikropalvelut ja REST-sovellusliittymät-oppimispolkuun, ja edistymisesi synkronoituu verkon ja CoddyKit-sovelluksen välillä. Spring Boot 4 -mikropalvelut ja REST-sovellusliittymät-kurssilla on yhteensä 4 oppituntia.

Koko määrityksen mukauttaminen

Päätepistekohtaisten annotaatioiden lisäksi voitte muotoilla koko dokumenttia – otsikkoa, versiota, yhteystietoja, lisenssiä, palvelimia ja suojausta – määrittämällä OpenAPI-beaniin.

OpenAPI-beanin määrittäminen

Palauttakaa OpenAPI-olio @Bean-metodista, jolloin SpringDoc käyttää sitä perusdokumenttina.

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                .title("Orders API")
                .version("v1")
                .description("Public ordering service"));
}

Info-osio

Info-olio sisältää Swagger UI:n yläosassa näytettävät metatiedot: otsikon, version, kuvauksen, käyttöehdot, yhteystiedot ja lisenssin.

new Info()
    .title("Orders API")
    .version("1.2.0")
    .contact(new Contact().name("API Team").email("api@acme.com"))
    .license(new License().name("Apache 2.0").url("https://apache.org/licenses/LICENSE-2.0"));

Palvelinten ilmoittaminen

Luetelkaa perus-URL-osoitteet, joissa API on saavutettavissa. Swagger UI antaa käyttäjien valita palvelimen, ja luodut asiakasohjelmat käyttävät näitä peruspolkuina.

new OpenAPI()
    .addServersItem(new Server().url("https://api.acme.com").description("Production"))
    .addServersItem(new Server().url("http://localhost:8080").description("Local"));

Miksi palvelimilla on merkitystä välityspalvelimen takana

Kun sovellus on yhdyskäytävän tai kontekstipolun takana, automaattisesti tunnistettu palvelimen URL-osoite voi olla väärä. Palvelinten ilmoittaminen eksplisiittisesti varmistaa, että "Try it out" -pyynnöt osuvat oikeaan osoitteeseen.

Suojausmallit

Dokumentoikaa, miten asiakkaat todentavat henkilöllisyytensä rekisteröimällä SecurityScheme-määrityksen komponentteihin, esimerkiksi bearer JWT:n.

new OpenAPI()
    .components(new Components()
        .addSecuritySchemes("bearerAuth",
            new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT")));

Suojauksen käyttöönotto maailmanlaajuisesti

Lisätkää SecurityRequirement, jotta käyttöliittymä näyttää lukkokuvakkeen ja antaa käyttäjien syöttää tunnisteen kaikkiin suojattuihin toimintoihin.

new OpenAPI()
    .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
    .components(/* scheme defined above */);

Toimintokohtainen suojaus

Jos haluatte suojata vain tietyt päätepisteet, käyttäkää ohjainmetodissa annotaatiota @SecurityRequirement sen sijaan, että ilmoittaisitte suojauksen maailmanlaajuisesti.

@SecurityRequirement(name = "bearerAuth")
@GetMapping("/admin/stats")
public Stats stats() { ... }

APIen ryhmittely GroupedOpenAPIlla

Suurissa sovelluksissa voitte jakaa dokumentaation nimettyihin ryhmiin (esimerkiksi julkisiin ja ylläpitäjän ryhmiin) käyttämällä GroupedOpenApi-luokkaa. Jokaisella ryhmällä voi olla omat polunsovittimensa.

@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("public")
            .pathsToMatch("/public/**")
            .build();
}

Mukauttaminen ominaisuuksien avulla

Jotkin asetukset voi määrittää ilman koodia springdoc.*-ominaisuuksilla – esimerkiksi toimintojen järjestyksen, skannattavat paketit ja mukaan otettavat polut.

# application.yml
springdoc:
  packages-to-scan: com.acme.api
  paths-to-match: /api/**
  swagger-ui:
    operations-sorter: method

OpenApiCustomizer tarkkaan hallintaan

Jos haluatte tehdä ohjelmallisia muutoksia jokaiseen toimintoon, toteuttakaa OpenApiCustomizer-bean ja muuttakaa dokumenttia luomisen jälkeen – voitte esimerkiksi lisätä yhteisen otsakkeen kaikkiin polkuihin.

Pikatarkistus

Testatkaa määrityksen mukauttamista koskeva ymmärryksenne.

Vastaa interaktiivisessa oppitunnissa

Kertaus

Mukautitte koko dokumenttia:

  • OpenAPI-bean määrittää Info-osion, palvelimet ja suojauksen
  • Ilmoittakaa palvelimet välityspalvelimia ja kontekstipolkuja varten
  • SecurityScheme + SecurityRequirement dokumentoivat todennuksen
  • GroupedOpenApi jakaa suuret API:t ryhmiin
Aloita maksutta

Opi Java tekoälytuutorin avulla — ilmaiseksi

Kirjoita ja suorita oikeaa koodia selaimessa, saa välitöntä apua tekoälytuutorilta ympäri vuorokauden ja jatka siitä, mihin jäit, verkossa tai sovelluksessa.

Kurssit
24
Oppitunnit
93
Aloita opiskelu maksuttaNäytä koko kurssi

Usein kysytyt kysymykset

Onko oppitunti ”OpenAPI-määrityksen mukauttaminen” ilmainen?

Kyllä – oppitunnin ”OpenAPI-määrityksen mukauttaminen” koko tekstin voi lukea täällä verkossa ilmaiseksi. Jos haluat harjoitella interaktiivisesti sisäänrakennetulla koodieditorilla ja ympäri vuorokauden käytettävissä olevan tekoälytuutorin avulla sekä avata koko Spring Boot 4 -mikropalvelut ja REST-sovellusliittymät-kurssin, päivitä CoddyKit PROhon. Spring Boot 4 -mikropalvelut ja REST-sovellusliittymät-kurssilla on yhteensä 4 oppituntia.

Mitä opin oppitunnilla ”OpenAPI-määrityksen mukauttaminen”?

Lisätkää metatietoja, palvelimia ja suojausmalleja. Harjoittelet Spring Boot 4 -mikropalvelut ja REST-sovellusliittymät-aihetta koodilla, jonka suoritat suoraan selaimessa. Ympäri vuorokauden käytettävissä oleva tekoälytuutori vastaa kysymyksiisi oppitunnin aikana.

Tarvitsenko kokemusta aloittaakseni Spring Boot 4 -mikropalvelut ja REST-sovellusliittymät-opiskelun?

Aiempi kokemus ei ole tarpeen. CoddyKitin Spring Boot 4 -mikropalvelut ja REST-sovellusliittymät-oppimispolku sopii vasta-alkajista edistyneisiin, joten voit aloittaa tästä tai alusta ja edetä omaan tahtiisi. Tämä on oppitunti 3/4.

Kuinka kauan ”OpenAPI-määrityksen mukauttaminen”-oppitunnin suorittaminen kestää?

Useimmat CoddyKitin oppitunnit kestävät noin 5–10 minuuttia. Jokainen oppitunti on lyhyt ja interaktiivinen, joten edistyt tasaisesti ja voit jatkaa siitä, mihin jäit – sekä verkossa että sovelluksessa.

Voinko kirjoittaa ja suorittaa koodia tällä Spring Boot 4 -mikropalvelut ja REST-sovellusliittymät-oppitunnilla?

Kyllä. Jokainen Spring Boot 4 -mikropalvelut ja REST-sovellusliittymät-oppitunti sisältää sisäänrakennetun koodieditorin, joten voit kirjoittaa ja suorittaa oikeaa koodia suoraan selaimessa ja saada välitöntä palautetta tekoälyltä – paikallista asennusta ei tarvita.

Kaikki tämän kurssin oppitunnit

  1. SpringDocin lisääminen projektiin
  2. Päätepisteiden ja mallien dokumentointi
  3. OpenAPI-määrityksen mukauttaminen
  4. Swagger UI
← Takaisin: Spring Boot 4 -mikropalvelut ja REST-sovellusliittymät