Preskoči na glavni sadržaj

Spring Boot integracija Knife4j, uljepšavanje i pojačavanje ružnog Swagger-a

Chenmo Wang ErJava razvoj na nivou preduzećaSpring Boot1081 reči4 minuta

Obično pri razvoju Spring Boot projekata sa odvojenim front-endom i back-endom, koristimo Swagger (kliknite na link za detaljnije informacije).

Ali s neprestanim povećanjem funkcionalnosti sistema, eksplozivnim rastom broja interfejsa, Swagger-ovo iskustvo korisnika postaje sve gore i gore, na primer kada su parametri zahteva JSON, ne može da se formatira, rezultati se ne mogu sklopiti, i nema funkcije pretrage.

Danas ćemo predstaviti glavnog protagonista Knife4j koji nadoknađuje ove nedostatke i daje Swagger-u jaču vitalnost i izražajnost.

O Knife4j-u

Knife4j-ov prethodnik je swagger-bootstrap-ui, pojačani UI implementacija springfox-swagger-ui-ja. swagger-bootstrap-ui koristi hibridni metod mešanja front-end UI-ja i back-end Java kôda, u microservice scenarijima izgleda veoma nepotrebno, poboljšani Knife4j je manji, lakši, a funkcionalnost je moćnija.

springfox-swagger-ui sučelje izgleda ovako, iskreno, malo je ružno.

swagger-bootstrap-ui pojačano izgleda ovako. Čisto intuitivno, zaista je pojačano.

Poboljšani Knife4j nije samo elegantniji i cooliji na sučelju, već je funkcionalniji: back-end Java kôd i front-end UI moduli su odvojeni, u microservice scenarijima je fleksibilnije; takođe pruža rešenje za pojačavanje fokusirano na Swagger.

Zvanična dokumentacija:

https://doc.xiaominfo.com/knife4j/documentation/

Gitee adresa:

https://gitee.com/xiaoym/knife4j

Adresa primera:

https://gitee.com/xiaoym/swagger-bootstrap-ui-demo

Integracija Knife4j-a

Knife4j potpuno prati Swagger-ov način korišćenja, tako da se može bezbedno prebaciti.

Prvi korak, dodajte Knife4j zavisnost u pom.xml fajlu (ne treba dodavati springfox-boot-starter, jer Knife4j starter već sadrži).

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--pri citanju molim vas da preuzmete najnoviju verziju 3.X sa maven centralnog repozitorijuma-->
    <version>3.0.2</version>
</dependency>

Drugi korak, konfiguracijska klasa SwaggerConfig je i dalje ista kao iz Swagger perioda.

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        Docket docket = new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo()).enable(true)
                .select()
                //apis: dodajte swagger opseg izdvajanja interfejsa
                .apis(RequestHandlerSelectors.basePackage("top.codingmore.controller"))
                .paths(PathSelectors.any())
                .build();

        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title="Bilješke praktičnog projekta programskog mačaka")
                .description("Programski mačak je Spring Boot+Vue projekat sa odvojenim front-endom i back-endom")
                .contact(new Contact("Chenmo Wang Er", "https://codingmore.top","www.qing_gee@163.com"))
                .version("v1.0")
                .build();
    }
}

Treći korak, kreirajte test kontroler klasu Knife4jController.java:

@Api(tags = "Test Knife4j")
@RestController
@RequestMapping("/knife4j")
public class Knife4jController {

    @ApiOperation("Test")
    @RequestMapping(value ="/test", method = RequestMethod.POST)
    public String test() {
        return "Chenmo Wang Er je ruzan i ruzan";
    }
}

Četvrti korak, budući da verzija springfox 3.0.x i verzija Spring Boot 2.6.x imaju konflikt, treba prvo rešiti ovaj bag, ukupno dva koraka (već sam objasnio u Swagger članku, ovde neću ponavljati, ali da bi spriječio da prijatelji ponovo zapadnu u rupu prilikom učenja, ovde ću ponoviti korake).

Prvo dodajte u application.yml fajl:

spring:
  mvc:
    path match:
      matching-strategy: ANT_PATH_MATCHER

Zatim dodajte u SwaggerConfig.java:

@Bean
public static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() {
    return new BeanPostProcessor() {

        @Override
        public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
            if (bean instanceof WebMvcRequestHandlerProvider || bean instanceof WebFluxRequestHandlerProvider) {
                customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
            }
            return bean;
        }

        private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings(List<T> mappings) {
            List<T> copy = mappings.stream()
                    .filter(mapping -> mapping.getPatternParser() == null)
                    .collect(Collectors.toList());
            mappings.clear();
            mappings.addAll(copy);
        }

        @SuppressWarnings("unchecked")
        private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean) {
            try {
                Field field = ReflectionUtils.findField(bean.getClass(), "handlerMappings");
                field.setAccessible(true);
                return (List<RequestMappingInfoHandlerMapping>) field.get(bean);
            } catch (IllegalArgumentException | IllegalAccessException e) {
                throw new IllegalStateException(e);
            }
        }
    };
}

Nakon završetva svih gore navedenih koraka, počnite sa sledećim korakom, inače će se ili pri pokretanju projekta desiti greška, ili u dokumentaciji nećete videti testni interfejs dokumentacije.

Peti korak, pokrenite Spring Boot projekat, u adresnoj traci pretraživača unesite sledeću adresu da posetite API dokumentaciju, pogledajte efekte.

Adresa za pristup (različito od Swagger-a): http://localhost:8080/doc.html

Zar je Knife4j jednostavniji i lepši od Swagger-a? Ako želite testirati interfejs, možete direktno kliknuti na interfejs, zatim kliknuti "test", kliknuti slanje da vidite povratne rezultate.

Funkcionalne karakteristike Knife4j-a

U praktičnom projektu programskog mačka će je već integrisan Knife4j, nakon što ga pokrenete lokalno, možete videti sve API interfejse. Upravni terminal programskog mačaka (codingmore-admin) koristi port 9002, nakon pokretanja servisa, u pretraživaču unesite http://localhost:9002/doc.html da ga posetite.

Evo kratkog predstavljanja funkcionalnih karakteristika Knife4j-a:

1) Podrška za prijavu autentifikacije

Knife4j kao i Swagger podržava autentifikaciju zaglavlja, kliknite "authorize" meni, dodajte informacije nakon prijave da biste zadržali token autentifikacije prijave.

Ako neki API zahteva autentifikaciju prijave, donosiće prethodno unešene informacije.

2) Podrška za JSON sklapljanje

Swagger ne podržava JSON sklapljanje, kada se vrati mnogo informacija, sučelje će izgledati veoma nepotrebno. Knife4j je drugačiji, može da sklapa čvorove povratnog JSON-a.

3) Offline dokumentacija

Knife4j podržava izvoz API dokumentacije u offline dokumentaciju (podržava markdown format, HTML format, Word format),

Nakon otvaranja u Typori izgleda ovako, veoma lepo i elegantly.

4) Globalni parametri

Kada neki zahtevi zahtevaju globalne parametre, ova funkcionalnost je veoma praktična, Knife4j podržava dva načina: header i query.

Nakon toga prilikom slanja zahteva donosiće ovaj globalni parametar.

5) Pretraga API interfejsa

Swagger nema funkciju pretrage, kada ima mnogo interfejsa za testiranje, kada treba pronaći određeni API, ne Mozete da uradite ništa osim da pomerate scrollbar da biste ga pronašli.

U gornjem desnom uglu dokumentacije, Knife4j pruža funkciju pretrage dokumentacije, unesite ključnu reč za pretragu, možete filtrirati i pretraživati, zar nije veoma pogodno?

Trenutno podržava pretragu adrese, naziva i opisa interfejsa.

EPILOG

Pored pojačanih funkcija koje sam gore naveo, Knife4j pruža mnogo praktičnih funkcija, prijatelji mogu probati jednu po jednu putem zvaničnog sajta, proizvodna efikasnost će se poboljšati dosta.

https://doc.xiaominfo.com/knife4j/documentation/enhance.html

Više sadržaja je otvoreno samo za korisnik planete "Erge-n napredni put do Java-e", potrebni prijatelji mogu kliknuti na link 🔗 da se pridruže našoj planeti, zajedno učimo, zajedno se takmičimo.. Programski mačak 🐱 je Spring Boot+Vue projekat sa odvojenim front-endom i back-endom, integriše najvažnije tehnološke tačke na tržištu. Kroz učenje praktičnog projekta možete provjeriti naučeno znanje kroz praksu, možete proširiti svoje tehničke granice, možete savladati kako jedan pravi praktični projekat ide od 0 do 1.

Putanja izvornog kôda