web-dev-qa-db-ja.com

REST APIのSwagger UIドキュメントの生成

JavaでJAX-RS/Jerseyを使用して開発したAPI REST。APIをSwaggerベースのUIドキュメントに変換/生成したい。申し訳ありませんが、サイトに記載されている手順は私にとってはあいまいです。

javaswaggerswagger-ui
26
user3767923

Swagger-coreをアプリケーションに統合するにはいくつかの方法がありますが、説明に基づいて、 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を直接それらに取り込むため、インタラクションの完全なセットを確認できます。

6
Ron

私が知っている最も簡単な方法は、JAXRS Analyzer mavenプラグインを使用することです。 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>

これにより、mvn clean installでswagger jsonが作成されます。私の知る限り、web.xmlなどを操作する必要はありません。バイトコード分析を介して行うためです。

ソース：Adam Bienウェブログ entry ＆airhacksセッションの1つでの彼のデモ

ボーナス：9分 ビデオ 使用法を説明するプラグインの作成者による

6
dubes

Swaggerには、GitHubでの段階的な実装のニースドキュメントがあります。

メソッド、リソース、モデルでSwaggerアノテーションを使用する必要があります。次に、 ここで説明されているようにweb.xmlを構成します 。これらのすべてのステップの後、swagger-ui yourdomain/api-docsまたはweb.xml ApiDeclarationServletのリスニングパスで設定された別のパスに到達できます。

サンプルswaggerアプリJax-rs/Jersey があります

Swagger UI は、Swagger準拠のAPIから美しいドキュメントとサンドボックスを動的に生成する、HTML、Javascript、およびCSSアセットの依存関係のないコレクションです。 Swagger UIには依存関係がないため、任意のサーバー環境またはローカルマシンでホストできます。

1
İlker Korkut

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; 
}
1
Master Mind