swagger-ui - SpringFox 和 Swagger UI - 如何记录/login 端点

Question

我已将 SpringFox 依赖项添加到我的 Spring Boot 项目中，当我打开 swagger-ui.html 页面时，我可以看到我自己创建的 RestControllers 的文档，我确实看到了以下文档:

• 基本错误 Controller
• 默认

“默认”选项卡包含对/api/login/端点的描述，但我找不到有关如何将此/api/login 端点配置为的文档:

• 将端点路径从/api/login 更改为/login
• 指定 HTTP 请求的正文以包含示例 JSON 模型，该模型应包含两个字段:电子邮件和密码。

我使用 Spring Security 并且/login 端点接受:用户能够登录的电子邮件和密码。

如何将文档添加到默认的/login 端点？

Answer 1

尝试配置这样的类来个性化您的登录。

package application.swagger;

import application.user.dto.UserLoginDTO;
import com.fasterxml.classmate.TypeResolver;
import java.util.*;
import lombok.extern.slf4j.Slf4j;
import org.springframework.core.annotation.Order;
import org.springframework.http.HttpMethod;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.OperationBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiDescription;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.ApiListingScannerPlugin;
import springfox.documentation.spi.service.contexts.DocumentationContext;
import springfox.documentation.spring.web.readers.operation.CachingOperationNameGenerator;
import springfox.documentation.swagger.common.SwaggerPluginSupport;

@Component
@Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER)
@Slf4j
public class SwaggerLoginListingScanner implements ApiListingScannerPlugin {

  // tag::api-listing-plugin[]
  private final CachingOperationNameGenerator operationNames;

  /**
   * @param operationNames - CachingOperationNameGenerator is a component bean
   *                       that is available to be autowired
   */
  public SwaggerLoginListingScanner(
    CachingOperationNameGenerator operationNames
  ) { //<9>
    this.operationNames = operationNames;
  }

  @Override
  public List<ApiDescription> apply(DocumentationContext context) {
    return new ArrayList<>(
      Arrays.asList(
        new ApiDescription(
          null,
          "/api/login",
          "login",
          Collections.singletonList(
            new OperationBuilder(operationNames)
              .summary("login")
              .tags(Set.of("jwt-authentication-filter"))
              .authorizations(new ArrayList<>())
              .position(1)
              .codegenMethodNameStem("loginPost")
              .method(HttpMethod.POST)
              .notes("This is a login method")
              .parameters(
                Arrays.asList(
                  new ParameterBuilder()
                    .description("Login Parameter")
                    .type(new TypeResolver().resolve(UserLoginDTO.class))
                    .name("userLogin")
                    .parameterType("body")
                    .parameterAccess("access")
                    .required(true)
                    .modelRef(new ModelRef("UserLoginDTO"))
                    .build()
                )
              )
              .responseMessages(responseMessages())
              .responseModel(new ModelRef(("UserToken")))
              .build()
          ),
          false
        )
      )
    );
  }

  /**
   * @return Set of response messages that overide the default/global response messages
   */
  private Set<ResponseMessage> responseMessages() { //<8>
    return Set.of(
      new ResponseMessageBuilder()
        .code(200)
        .responseModel(new ModelRef("UserToken"))
        .build(),
      new ResponseMessageBuilder()
        .code(401)
        .responseModel(new ModelRef("ApiError"))
        .build(),
      new ResponseMessageBuilder()
        .code(403)
        .responseModel(new ModelRef("ApiError"))
        .build(),
      new ResponseMessageBuilder()
        .code(404)
        .responseModel(new ModelRef("ApiError"))
        .build()
    );
  }

  // tag::api-listing-plugin[]

  @Override
  public boolean supports(DocumentationType delimiter) {
    return DocumentationType.SWAGGER_2.equals(delimiter);
  }
}