web-dev-qa-db-fra.com

Comment générer la spécification OpenApi 3.0 à partir de l'application Spring Boot existante?

J'ai un projet (Spring Boot App + Kotlin) pour lequel j'aimerais avoir une spécification Open API 3.0 (de préférence en YAML). Les bibliothèques Springfox sont agréables mais elles génèrent Swagger 2.0 JSON. Quelle est la meilleure façon de générer une spécification Open Api 3.0 à partir des annotations de mes contrôleurs? L'écrire à partir de zéro est-il le seul moyen?

spring-bootkotlinswaggeropenapi
15
ladyskynet

Nous avons utilisé la bibliothèque springdoc-openapi dans notre projet kotlin, et elle répond à notre besoin d'automatiser la génération de documentation API à l'aide de projets Spring Boot.

Il déploie automatiquement swagger-ui sur une application Spring-Boot

La page Swagger UI devrait alors être disponible sur: - http: // server: port/context-path/swagger-ui.html La description OpenAPI sera disponible à l'url suivante pour le format json: - http: // serveur: port/chemin-contextuel/v3/api-docs

Ajoutez la bibliothèque à la liste de vos dépendances de projet (aucune configuration supplémentaire n'est nécessaire)

 <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.2.32</version>
  </dependency>
8
ouled saber

Vous pouvez regarder spring-restdocs et restdocs-api-spec .

spring-restdocs adopte une approche pilotée par les tests de la documentation de l'API qui présente de nombreux avantages par rapport à l'approche pilotée par l'introspection utilisée par spring-fox. restdocs-api-spec est une extension pour spring-restdocs qui ajoute la prise en charge des spécifications API. Actuellement, il prend en charge OpenAPI2 OpenAPI3 et Postman.

4
Mathias Dpunkt

J'ai décidé d'implémenter mon propre générateur https://github.com/jrcodeza/spring-openapi peut-être pouvez-vous le vérifier aussi. Il est basé sur la réflexion et prend en charge les annotations javax et ressort. Il génère également un modèle d'héritage (avec discriminateurs) basé sur les annotations de Jackson. De plus, vous pouvez définir vos propres intercepteurs si vous souhaitez modifier le processus de génération (par exemple lorsque vous avez vos propres annotations et devez ajuster les sections générées du schéma). Vous pouvez l'utiliser en mode runtime ou en tant que plugin maven. Il existe également OpenAPI3 à Java, qui génère le modèle à partir des spécifications openapi3. Encore une fois, il génère également des annotations Javax et des annotations Jackson pour un héritage correct.

3
Jakub Remenec

Si vous utilisez jax-rs, ce tutoriel vous aide. Il utilise l'implémentation Apache CXF. Je n'ai trouvé aucune autre implémentation de jaxrs qui utilise Spring Boot ET génère une spécification Open API 3.0.

Vous aurez besoin de ces dépendances:

<dependency>
    <groupId>org.Apache.cxf</groupId>
    <artifactId>cxf-rt-rs-service-description-openapi-v3</artifactId>
    <version>3.2.4</version>
</dependency>

<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>swagger-ui</artifactId>
    <version>3.13.6</version>
</dependency>

Voici la configuration générale, plus de détails sont dans le lien:

@Configuration
@EnableAutoConfiguration
@ComponentScan(basePackageClasses = PeopleRestService.class)
public class AppConfig {
    @Autowired private PeopleRestService peopleRestService;
    @Bean(destroyMethod = "destroy")
    public Server jaxRsServer(Bus bus) {
        final JAXRSServerFactoryBean factory = new JAXRSServerFactoryBean();
        factory.setApplication(new JaxRsApiApplication());
        factory.setServiceBean(peopleRestService);
        factory.setProvider(new JacksonJsonProvider());
        factory.setFeatures(Arrays.asList(new OpenApiFeature()));
        factory.setBus(bus);
        factory.setAddress("/");
        return factory.create();
    }
    @Bean
    public ServletRegistrationBean cxfServlet() {
        final ServletRegistrationBean servletRegistrationBean = new ServletRegistrationBean(new CXFServlet(), "/api/*");
        servletRegistrationBean.setLoadOnStartup(1);
        return servletRegistrationBean;
    }
}

https://dzone.com/articles/moving-with-the-times-towards-openapi-v300-adoptio

1
Jerry Li