Создание документации пользовательского интерфейса Swagger для REST API

Ответ 1

Существует несколько способов интеграции ядра swagger с вашим приложением, но на основе вашего описания я просто буду следовать странице wiki, как описано в https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5 или https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-2.X-Project-Setup-1.5 в зависимости от используемой вами версии Джерси.

Эти страницы также ссылаются на набор образцов, которые вы можете использовать для справки, и посмотрите, как они работают. Они также втягивают swagger-ui прямо в них, чтобы вы могли видеть полный набор взаимодействий.

Ответ 2

Самый простой способ - использовать JAXRS Analyzer maven plugin. Который можно найти на GitHub

<plugin>
<groupId>com.sebastian-daschner</groupId>
<artifactId>jaxrs-analyzer-maven-plugin</artifactId>
<version>0.4</version>
<executions>
    <execution>
        <goals>
            <goal>analyze-jaxrs</goal>
        </goals>
        <configuration>
            <!-- Available backends are plaintext (default), swagger and asciidoc -->
            <backend>plaintext</backend>
            <!-- Domain of the deployed project, defaults to example.com -->
            <deployedDomain>example.com</deployedDomain>
        </configuration>
    </execution>
</executions>

Это создает swagger json для вас с чистой установкой mvn. Насколько я знаю, он не нуждается в каких-либо манипуляциях с web.xml и т.д., Поскольку он делает это с помощью анализа байт-кода.

Источник: Adam Bien weblog entry и его демо на одном из сеансов аэрофоруса

Бонус: 9-минутный video создатель плагина, объясняющий использование

Ответ 3

У Swagger есть хорошая документация поэтапной реализации на github.

Вы должны использовать аннотации swagger для ваших методов, ресурсов, моделей. Затем вы должны настроить свой web.xml, как описано здесь. После всех этих шагов вы можете достигнуть swagger-ui yourdomain/api-docs или другого пути, настроенного в пути прослушивания web.xml ApiDeclarationServlet.

Существует приложение для выборки Jax-rs/Jersey

Swagger UI - это коллекция без HTML, Javascript и CSS, не зависящая от зависимостей, которая динамически генерирует красивую документацию и песочницу из Swagger-совместимого API. Поскольку пользовательский интерфейс Swagger не имеет зависимостей, вы можете разместить его в любой серверной среде или на локальной машине.

• Существует хорошая дискуссия о том, чтобы получить зависимость от статики. Обычно вам нужно скопировать и вставить статистику swagger-ui. https://github.com/swagger-api/swagger-ui/issues/758
• Распространение пользовательского интерфейса Swagger https://github.com/swagger-api/swagger-ui/tree/master/dist
• Еще одно примерное приложение, использующее swagger: https://github.com/apache/camel/blob/master/examples/camel-example-servlet-rest-tomcat/src/main/webapp/WEB-INF/web.xml
• Простая ссылка о реализация swagger с помощью springboot (в этой ситуации не требуется web.xml).

Ответ 4

Вы должны использовать roaster: вы можете изменить исходный код, чтобы добавить новые аннотации. Вот пример, чтобы проиллюстрировать, как использовать его в вашем случае:

package ma.cars.iscraper;

import org.jboss.forge.roaster.Roaster;
import org.jboss.forge.roaster.model.source.*;

import java.util.List;

public class Main {

    public static void main(String[] args) {



  String originalClassSourceCode = "@Path(\"user\")\n public class SomeClass {    @GET\n" +
                "  @Path(\"{userId}\")\n  public Response getUserById() {\n return null; \n}";

        System.out.println("Before : \n" + originalClassSourceCode);
  JavaClassSource javaClass =
                Roaster.parse(JavaClassSource.class,originalClassSourceCode );

       String pathValue = null;
        // extract Path annotation value
        List<AnnotationSource<JavaClassSource>> listAnnotations = javaClass.getAnnotations();
        for (AnnotationSource annotation :listAnnotations) {
            if (annotation.getName().equals("Path")) {
                pathValue = annotation.getStringValue();
            }
        }
        AnnotationSource<JavaClassSource> apiAnnotation = javaClass.addAnnotation("com.wordnik.swagger.annotations.Api");
        apiAnnotation.setLiteralValue("\"" + pathValue + "\"") ;

        List<MethodSource<JavaClassSource>> methods = javaClass.getMethods();

        for (MethodSource<JavaClassSource> method: methods) {
           for (AnnotationSource annotation: method.getAnnotations()) {
               if (annotation.getName().equals("DELETE") || annotation.getName().equals("GET")
                       || annotation.getName().equals("POST") || annotation.getName().equals("PUT")) {
                   String returnTypeClass = method.getReturnType().getQualifiedName();
                   AnnotationSource<JavaClassSource> apiOperation = method.addAnnotation("com.wordnik.swagger.annotations.ApiOperation");
                   apiOperation.setLiteralValue("value", "\"value\"");
                   apiOperation.setLiteralValue("response", "\"" + returnTypeClass + ".class\"");

               }
           }
        }

        System.out.println(javaClass);

    }
}

И вот вывод:

Before : 
@Path("user")
 public class SomeClass {    @GET
  @Path("{userId}")
  public Response getUserById() {
 return null; 
}
After :

import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;@Path("user")
 @Api("user")
public class SomeClass {    @GET
  @Path("{userId}")
  @ApiOperation(value = "value", response = "Response.class")
public Response getUserById() {
 return null; 
}