swagger-katharsis (community growth)

[masterspambot]

From @ieugen on March 29, 2016 8:24

Hello,

I'm looking for API docuemntation adn I found [1] . It's a bit behind but I think it can be improved and it would be nice to have it as part of the community.

I propose we ask @woonsan if he is willing to maintain swagger-katharsis as part and under katharsis-project, provided of course the other team members agree.

Wdyt @meshuga , @masterspambot ? I'm willing to contribute to the project since I will need to document the API for the project. I'm more inclined to do an offline annotation parsing solution to generate the docs on build for a specific version.

[1] https://github.com/woonsan/swagger-katharsis

Copied from original issue: katharsis-project/katharsis-core#273

[masterspambot]

From @woonsan on March 29, 2016 13:10

I'm very willing to put that in katharsis-project if accepted. :-) Actually my goal was to make it working with basic features at least and propose it to katharsis. But unfortunately, I couldn't find enough time to make it for some other work to do. Its status is just an initial experiment at the moment.
Anyway, I guess we have another volunteer at least to make it work. So, I'm very willing to work with you guys and if you guys like it, I can transfer it to katharsis-project, too.

[masterspambot]

From @keithdmoore on March 29, 2016 13:19

There is also this placeholder project. https://github.com/meshuga/katharsis-springfox

[masterspambot]

Personally I have nothing against it, but as far as I know @ieugen has still some work to do with katharsis-vertex and we are gonna need maintainer for this repo... Can we handle that?

[masterspambot]

From @ieugen on March 29, 2016 15:15

@masterspambot The idea behind a community is to give authority. .

If we have an open process of how people can contribute then things can move with minimal intervention.

Regarding my work on katharsis-vertx: I can allready publish to jcenter. I'm going to sync with Maven tomorrow. Other then that, most of the features are ok.

@keithdmoore : what about springfox? it seems empty.

[remmeier]

related topics:
OAI/OpenAPI-Specification#476
OAI/OpenAPI-Specification#519

[nilportugues]

As of now, I recommend to do this by adding an Interface to the "Repository" class.

The implemented interface can hold the Annotations for Swagger and the documentation can be generated.

I have done this with spring-boot and springfox. No problems at all.

[charybr]

Hi nilportugues,

It would be great, if you can provide a sample.

Thanks!
Chary

[nilportugues]

@charybr sure can.

In your pom.xml 's dependencies:

        <!-- SWAGGER -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox-version}</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-core</artifactId>
            <version>${swagger-core-version}</version>
        </dependency>

Then, let's say you have a controller... for instance:

import io.katharsis.repository.annotations.*;
import io.katharsis.response.JsonApiResponse;
import io.swagger.annotations.ApiParam;
import org.springframework.data.domain.Page;
import org.springframework.web.bind.annotation.PathVariable;

import javax.inject.Inject;
import javax.inject.Named;
import javax.servlet.http.HttpServletRequest;

@Named
@JsonApiResourceRepository(Message.class)
public class MessageController implements IMessageController{

    @JsonApiDelete
    public void delete(@PathVariable("id") @ApiParam(value = "Message Id") String id) throws Exception    {
        messageDeleterService.delete(id);
    }
}

Notice the IMessageController, this is it's implementation:

import io.katharsis.response.JsonApiResponse;
import io.swagger.annotations.*;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import springfox.documentation.annotations.ApiIgnore;

@Controller
public interface IMessageController {

    @ApiResponses({
        @ApiResponse(code = 204, message = "No Content"),
        @ApiResponse(code = 404, message = "Not Found"),
    })
    @ApiOperation(
        value = "Delete a Message.",
        nickname = "deleter",
        tags = {"API Message"}
    )
    @RequestMapping(
        path = "api/messages/{id}", //THIS NEEDS TO MATCH WHAT KATHARSIS GENERATES.
        method= RequestMethod.DELETE,
        produces = "application/vnd.api+json"
    )
    void delete(@PathVariable("id") @ApiParam(value = "Message Id") String id) throws Exception;

}

You won't get the models in Swagger for POST, PUT or PATCH. But you'll get very basic Swagger going on.

[charybr]

Thanks a lot, nilportugues!

[chb0github]

We need to roll in SOME kinda support for a UI. I am in favor of this

[chb0github]

I have been looking at this and I don't see a clear means of doing this. I checked out what meshuga had done and, no surprise, there is no root resource to discover. So, when you hit / you get a 500 error. I posted about this a while ago. I will continue to investigate now that I have some time but the lack of a root issue will likely be a show stopper

[chb0github]

After careful deliberation, the counsel of elders has decreed that this shall not be supported. We believe in hypermedia. It's our belief that swagger cannot support the level of functionality as described in JSON API.

Thanks for your cooperation,

The Management.