001/**
002 * Copyright (C) 2006-2025 Talend Inc. - www.talend.com
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.talend.sdk.component.server.api;
017
018import static javax.ws.rs.core.MediaType.APPLICATION_JSON;
019import static org.eclipse.microprofile.openapi.annotations.enums.ParameterIn.PATH;
020import static org.eclipse.microprofile.openapi.annotations.enums.ParameterIn.QUERY;
021import static org.eclipse.microprofile.openapi.annotations.enums.SchemaType.OBJECT;
022import static org.eclipse.microprofile.openapi.annotations.enums.SchemaType.STRING;
023
024import javax.ws.rs.DefaultValue;
025import javax.ws.rs.GET;
026import javax.ws.rs.Path;
027import javax.ws.rs.PathParam;
028import javax.ws.rs.Produces;
029import javax.ws.rs.QueryParam;
030import javax.ws.rs.core.MediaType;
031
032import org.eclipse.microprofile.openapi.annotations.Operation;
033import org.eclipse.microprofile.openapi.annotations.media.Content;
034import org.eclipse.microprofile.openapi.annotations.media.Schema;
035import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
036import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
037import org.eclipse.microprofile.openapi.annotations.tags.Tag;
038import org.talend.sdk.component.server.front.model.DocumentationContent;
039import org.talend.sdk.component.server.front.model.error.ErrorPayload;
040
041@Path("documentation")
042@Tag(name = "Documentation", description = "Endpoint to retrieve embedded component documentation.")
043public interface DocumentationResource {
044
045    @GET
046    @Path("component/{id}")
047    @Produces(MediaType.APPLICATION_JSON)
048    @Operation(
049            description = "Returns a documentation in asciidoctor format for the given component.  " +
050                    "The component is represented by its identifier (`id`).")
051    @APIResponse(responseCode = "200",
052            description = "The list of available and storable configurations (datastore, dataset, ...).",
053            content = @Content(mediaType = APPLICATION_JSON))
054    @APIResponse(responseCode = "404",
055            description = "If the component is not found in the server," +
056                    " response will be an ErrorPayload with the code COMPONENT_MISSING.",
057            content = @Content(mediaType = APPLICATION_JSON,
058                    schema = @Schema(type = OBJECT, implementation = ErrorPayload.class)))
059    DocumentationContent getDocumentation(
060            @PathParam("id") @Parameter(name = "id",
061                    description = "The component identifier.", in = PATH) String id,
062            @QueryParam("language") @DefaultValue("en") @Parameter(name = "language",
063                    description = "The language requested.", in = QUERY,
064                    schema = @Schema(type = STRING, defaultValue = "en")) String language,
065            @QueryParam("segment") @DefaultValue("ALL") @Parameter(name = "segment",
066                    description = "The documentation part to extract. Available parts are: " +
067                            "`ALL` (default), `DESCRIPTION`, `CONFIGURATION`",
068                    in = QUERY,
069                    schema = @Schema(type = STRING, defaultValue = "ALL")) DocumentationSegment segment);
070
071    enum DocumentationSegment {
072        ALL,
073        DESCRIPTION,
074        CONFIGURATION
075    }
076}