Как создать документацию для интерфейса? - PullRequest
Новая
       92

Как создать документацию для интерфейса?

0 голосов
/ 13 марта 2020

Я его погуглил, но во всех примерах для документации о чванстве используются классы. Я хотел бы включить интерфейсы, поскольку читатель интересуется API, а не реализациями.

Вот мой код:

Включены требуемые зависимости maven: 

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>

My SpringBootApplication : 

package com.manojk.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

Мой интерфейс RestController 

package com.manojk.demo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value = "/") // this annotation needed for swagger-ui to work
public interface HelloWorldControllerInterface {
    @GetMapping
    String helloWorld();
}

И реализация 

package com.manojk.demo;

import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Component // this annotation needed to initialize this controller
public class HelloWorldController implements HelloWorldControllerInterface {
    @Override
    public String helloWorld(){
        return "Hello World";
    }
}

Все это поддерживается необходимой конфигурацией swagger: 

package com.manojk.demo;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import static springfox.documentation.builders.PathSelectors.regex;

/**
 * Configuration class for Swagger REST API documentation
 *
 */
@Configuration
@EnableSwagger2
/**
 * Run nad hit http://localhost:8080/swagger-ui.html to see it working
 */
public class SwaggerConfig {

  /**
   * @return Swagger Docker
   */
  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            // .apis(RequestHandlerSelectors.basePackage("com.siemens.oss.domain.controller.service")) # does not work for interfaces
            .apis(RequestHandlerSelectors.basePackage("com.manojk.demo")) // works for implementations
            .paths(regex("/.*"))
            .build();
  }
}

Код доступен в виде проекта maven на https://github.com/MKhotele/spring-examples/tree/master/demo.

http://localhost: 8080 / swagger-ui. html показывает «Hello World Controller»; но ничего для «Hello World Controller Interface».

Можно ли сделать так, чтобы Swagger включал интерфейс? Как?

1 Ответ

0 голосов
/ 14 марта 2020

Подсказка предоставлена ​​в комментариях Сергей Жевжик . Спасибо!

Это не должно быть возможно и, следовательно, невозможно.

Спецификация OpenAPI (ранее Swagger Specification) касается не только спецификации REST API. Это также о взаимодействии с ними. Интерфейс никогда не может предоставить конечную точку для взаимодействия; но только реализация.

Swagger - это набор инструментов с открытым исходным кодом, созданный на основе спецификации OpenAPI, который может помочь вам проектировать, создавать, документировать и использовать API-интерфейсы REST .

Как описано в Введение в OpenAPI-спецификацию ,

Спецификация OpenAPI (OAS) определяет стандартный, независимый от языка интерфейс для API RESTful, который позволяет и люди, и компьютеры, чтобы обнаружить и понять возможности службы без доступа к исходному коду, документации или через проверку трафика c. При правильном определении потребитель может понять и взаимодействовать с удаленной службой с минимальным количеством логики реализации c.

...