web-dev-qa-db-ja.com

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

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

Swaggerはかなりクールなソリューションのようですが、コードでSwaggerをどのように使用できるかわかりません。私はjsonswaggerを作成するための最良の方法を探しています-uiは読むことができます-どうすればよいですか？

また、そのような環境でRestAPIを文書化するための他の優れたソリューションを確認できれば幸いです。

javarestjerseydocumentation-generationswagger
9
Erik Sapir

私はSwaggerを試していませんが、 enunciate を試してみてください。 javadocフェーズの一部としてJAX-RSエンドポイントのドキュメントを生成できます。生成されたドキュメントのいくつかの例は、 enunciate page で入手できます。

更新

プロジェクトはに移動されました http://enunciate.webcohesion.com/ 、Java 8は次のバージョン2.0でサポートされます。

6
ragnor

Swagger-uiを有効にするには、ドキュメントから「そのまま」使用できます。

「swagger-uiコードをそのまま使用できます。ビルドや再コンパイルは必要ありません。このリポジトリのクローンを作成し、distフォルダーにあるビルド済みファイルを使用するだけです。swagger-uiをそのまま使用する場合は、ここで停止してください。 「」

したがって、基本的には、Webサーバーに「dist」コンテンツを配置するだけで済みます。次に、UIにWebサービスのSwaggerエンドポイントを入力します。例：http://localhost:8080/Webservice/api-doc.json（これは必要なアドレスエンドポイントと同じです） web.xmlで定義します）。

Swaggerを構成する必要のある場所がいくつかあるため、他の詳細が誤って構成されていると思われます。以下では、Swaggerでの私自身のセットアップの詳細をいくつか示します。

これは、私のweb.xmlのSwagger構成のスニペットです。

<!-- // 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パッケージのリストです。ここには、Swaggerドキュメントに示されているいくつかのリソースがあります（これは、セットアップしたときとは異なるように見えるので、ここにドキュメントの完全なリストがあります）。

enter image description here

これらのファイル（または例）は、Swaggerのサンプルプロジェクトにあります： https://github.com/wordnik/swagger-core/tree/master/samples/Java-jaxrs Swaggerをセットアップするための「テンプレート」として使用してみてください。私が問題を抱えた1つのファイルは、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。

5
emgsilva

JAX-RSとMavenを使用している場合は、 MireDot も試してみることを検討してください。セットアップは非常に簡単です。

4
Peter R.