swaggerまたは他のツールを使用してRest APIドキュメントを生成する

Question

私はRest APIを文書化する方法を探しています。 私のサーバーはTomcat/Springサーバーであり、Rest APIはJenkinsを使用して実装されています。

スガッガーはかなりクールな解決策だと思われますが、私は自分のコードでどのように使用できるのか分かりません。私はjson swaggerを作成するための最善の方法を探しています.uiは読むことができます - どうすればいいですか？

また、このような環境でレストAPIをドキュメント化するための他の優れたソリューションも確認していきます。

Answer 1

私はすごく試したことはありませんが、あなたはenunciateを試すことがあります。 javadocフェーズの一部としてJAX-RSエンドポイントのドキュメントを生成することができます。生成されたドキュメントのいくつかの例が

プロジェクトhttp://enunciate.webcohesion.com/に移動されたenunciate page

Updateで入手でき、Javaの8は、次期バージョン2.0でサポートされます。

Answer 2

威張っ-UIを有効にするには、あなたは "として - ある" それを使用することができます - ドキュメントから：

「あなたはAS-IS闊歩-UIコードを使用することはできませんんが構築する必要や recompile-を！ - このリポジトリを複製して、 distフォルダにある事前構築ファイルを使用してください。swagger-uiをそのまま使用したい場合は、ここで停止してください。これは、同じアドレスエンドポイントあなたです（http://localhost:8080/Webservice/api-doc.json：

だから、基本的に、あなたは、あなたが例えば、UIにおけるWebサービスの闊歩エンドポイントを入力して、Webサーバーに「DIST」の内容を配置するだけ必要がありますweb.xmlに定義する必要があります）。

スワッガーを構成する必要がある場所がいくつかあるため、他の詳細が誤って設定されている可能性があります。以下では、Swaggerで自分のセットアップの詳細をいくつか説明します。

これは私のweb.xmlに闊歩構成の抜粋です：闊歩ドキュメントに提示されるよう

<!-- // Jersey declaration --> 
<servlet> 
    <servlet-name>web service</servlet-name> 
    <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class> 
    <init-param> 
     <param-name>com.sun.jersey.config.property.packages</param-name> 
     <param-value>com.mywebservice;com.wordnik.swagger.jaxrs.listing;com.fasterxml.jackson.jaxrs</param-value> 
    </init-param> 
    <init-param> 
     <param-name>com.sun.jersey.config.property.classnames</param-name> 
     <param-value>com.mywebservice;com.wordnik.swagger.jaxrs.listing;com.fasterxml.jackson.jaxrs</param-value> 
    </init-param> 
    <init-param> 
     <param-name>swagger.api.basepath</param-name> 
     <param-value>http://localhost:8080/Webservice</param-value> 
    </init-param> 
    <init-param> 
     <param-name>api.version</param-name> 
     <param-value>0.0.2</param-value> 
    </init-param> 
    <load-on-startup>1</load-on-startup> 
</servlet> 
<servlet> 
    <servlet-name>Bootstrap</servlet-name> 
    <servlet-class>com.mywebservice.utils.swagger.Bootstrap</servlet-class> 
    <load-on-startup>1</load-on-startup> 
</servlet> 
<filter> 
    <filter-name>ApiOriginFilter</filter-name> 
    <filter-class>com.mywebservice.utils.swagger.ApiOriginFilter</filter-class> 
</filter> 
<filter-mapping> 
    <filter-name>ApiOriginFilter</filter-name> 
    <url-pattern>/*</url-pattern> 
</filter-mapping> 

ベローは今に思われる（いくつかのリソースがあるcom.mywebservice.utils.swaggerパッケージのリストです私はそれを設定する場合とは異なること、したがってここでは、文書の完全なリスト）である：

あなたが闊歩からサンプルプロジェクトでは、これらのファイル（または例）を見つけることができ

：https://github.com/wordnik/swagger-core/tree/master/samples/java-jaxrs、これは "テンプレート"として使ってみよう。私が問題を抱えていたファイルはApiListingResourceでした：

import javax.ws.rs.Path; 
import javax.ws.rs.Produces; 

import com.wordnik.swagger.annotations.Api; 
import com.wordnik.swagger.jaxrs.JavaApiListing; 

@Path("/resources.json") 
@Api("/resources") 
@Produces({ "application/json"}) 
public class ApiListingResource extends JavaApiListing{ 
} 

HTHです。

Answer 3

JAX-RSとmavenを使用している場合は、MireDotも試してみるとよいでしょう。設定はとても簡単です。