Springfoxソース分析(十七)Swagger 2インタフェースドキュメント例インタフェースapi-docs

先にswaggerのパケットインタフェース情報が取得され、次にパケット名に基づいて各パケットのSwaggerリソース詳細が取得され、springfoxに/v 2/api-docsインタフェースが提供されて取得される
インタフェースのソースコードを見てみましょう

@Controller
@ApiIgnore
public class Swagger2Controller {

  public static final String DEFAULT_URL = "/v2/api-docs";
  private static final Logger LOGGER = LoggerFactory.getLogger(Swagger2Controller.class);
  private static final String HAL_MEDIA_TYPE = "application/hal+json";

  private final String hostNameOverride;
  private final DocumentationCache documentationCache;
  private final ServiceModelToSwagger2Mapper mapper;
  private final JsonSerializer jsonSerializer;

  @Autowired
  public Swagger2Controller(
      Environment environment,
      DocumentationCache documentationCache,
      ServiceModelToSwagger2Mapper mapper,
      JsonSerializer jsonSerializer) {

    this.hostNameOverride =
        environment.getProperty(
            "springfox.documentation.swagger.v2.host",
            "DEFAULT");
    this.documentationCache = documentationCache;
    this.mapper = mapper;
    this.jsonSerializer = jsonSerializer;
  }

  @RequestMapping(
      value = DEFAULT_URL,
      method = RequestMethod.GET,
      produces = { APPLICATION_JSON_VALUE, HAL_MEDIA_TYPE })
  @PropertySourcedMapping(
      value = "${springfox.documentation.swagger.v2.path}",
      propertyKey = "springfox.documentation.swagger.v2.path")
  @ResponseBody
  public ResponseEntity getDocumentation(
      @RequestParam(value = "group", required = false) String swaggerGroup,
      HttpServletRequest servletRequest) {

    String groupName = Optional.fromNullable(swaggerGroup).or(Docket.DEFAULT_GROUP_NAME);
    Documentation documentation = documentationCache.documentationByGroup(groupName);
    if (documentation == null) {
      LOGGER.warn("Unable to find specification for group {}", groupName);
      return new ResponseEntity(HttpStatus.NOT_FOUND);
    }
    Swagger swagger = mapper.mapDocumentation(documentation);
    UriComponents uriComponents = componentsFrom(servletRequest, swagger.getBasePath());
    swagger.basePath(Strings.isNullOrEmpty(uriComponents.getPath()) ? "/" : uriComponents.getPath());
    if (isNullOrEmpty(swagger.getHost())) {
      swagger.host(hostName(uriComponents));
    }
    return new ResponseEntity(jsonSerializer.toJson(swagger), HttpStatus.OK);
  }

  private String hostName(UriComponents uriComponents) {
    if ("DEFAULT".equals(hostNameOverride)) {
      String host = uriComponents.getHost();
      int port = uriComponents.getPort();
      if (port > -1) {
        return String.format("%s:%d", host, port);
      }
      return host;
    }
    return hostNameOverride;
  }
}

このインタフェースの主なロジック:

groupNameグループ名パラメータが入力され、Documentationドキュメントオブジェクト

がドキュメントキャッシュオブジェクトから取得される.

mapperが提供する方法により、Documentationオブジェクトを標準的なSwaggerオブジェクト

に変換する.

JSON応答出力

Swaggerの標準オブジェクトには主に情報が含まれています.前にも紹介しました.

public class Swagger {
    protected String swagger = "2.0";
    protected Info info;
    protected String host;
    protected String basePath;
    protected List tags;
    protected List schemes;
    protected List consumes;
    protected List produces;
    protected List security;
    protected Map paths;
    protected Map securityDefinitions;
    protected Map definitions;
    protected Map parameters;
    protected Map responses;
    protected ExternalDocs externalDocs;
    protected Map vendorExtensions;
}

最終的にui側でSwaggerの属性情報を取得してインタフェースの情報レンダリングを行い、開発者はインタフェースの表示とデバッグを行うことができる.