swagger #swagger

Size: px

Start display at page:

Download "swagger #swagger"

ゆりかすすむ
2 years ago
Views:

1 swagger #swagger

2 1 1: 2 2 Examples Node.js 2 2: 4 Examples spring-bootswagger-uispringfox 4 1 Mavenspringfox API 5 3: 7 7 Examples 7 REST WSswagger-ui 7 15

3 You can share this PDF with anyone you feel could benefit from it, downloaded the latest version from: swagger It is an unofficial and free swagger ebook created for educational purposes. All the content is extracted from Stack Overflow Documentation, which is written by many hardworking individuals at Stack Overflow. It is neither affiliated with Stack Overflow nor official swagger. The content is released under Creative Commons BY-SA, and the list of contributors to each chapter are provided in the credits section at the end of this book. Images may be copyright of their respective owners unless otherwise specified. All trademarks and registered trademarks are the property of their respective company owners. Use the content presented in this book at your own risk; it is not guaranteed to be correct nor accurate, please send your feedback and corrections to 1

4 1: スワッガーをいめるこのセクションではなもののとがそれをするについてをしますまたなテーマをスワッガーでしするトピックにリンクするがあります swaggerのドキュメントはしくなっているのでそれらのトピックのバージョンをするがあります Examples はじめに - インストール - セットアップ Node.js でのき Swaggerは REST APIをするのの / ですコードジェネレータやエディタなどのなをにかつにされたツールのエコシステムをします Swaggerのもなはメソッドパラメータモデルのドキュメントがサーバーコードににされているため APIがにしていることですここではがスウィガーなのかのなをすリンクがありますは JSONまたはYAMLでできますそしてたちはそれにじてスワッガーをっています.jsonまたはswagger.yamlファイルオンラインエディタをしてファイルをできますのをするリンクがあります http : //swagger.io/specification/ スワッガーをする 1. APIファーストアプローチトップダウンアプローチスワッガーエディタをスワッガーをく swagger-codegenとswagger-uiをしてapiを 2. サービスの1のアプローチボトムアップアプローチスワッガーアノテーションをしてJAX- RSリソースクラスをする swaggerコアをしてスワッガーをにする swagger-codegenと swagger-uiをしてクライアントapiとドキュメントをするは swagger mavenプラグインのmavenビルドにうことができますインストールとセットアップこのセクションでは swaggerをインストールし swagger UIをセットアップしそれをしてサーバーとクライアントSDKをします Node Package Managerをしてswaggerをインストールするにはのコマンドをします npm install -g swagger '-g' フラグをするとモジュールがグローバルにインストールされますにのコマンドをしてプロジェクトをします swagger project create <project-name> これによりユーザーに REST API をするためのフレームワークをするようめられます Express 2

5 をじものにしてすることができますこれによりのとそれぞれに README.md ファイルをむプロジェクトディレクトリがされます API / コントローラ / ヘルパー / モック / スワッガー / config / テスト / API / コントローラ / ヘルパー app.js package.json サーバーはにができておりこのコマンドをしてプロジェクトルートですることができます swagger project start ホストサーバーが localhost としてされていて app.js ファイルでポートがされていないサーバーはからされますここでスワッガー UI をして REST API をさらにできますこれはをしてしいですることができます swagger project edit これによりにされたポートのブラウザタブでスワッガーエディタがきますサンプルの hello GET はすでに swagger.yaml ファイルにしていますこのファイルをさらにするとサーバーはそれでします paths セクションで x-swagger-router-controller されるは controllers フォルダの javascript ファイルにするがありますサンプルとして hello_world.js が controllers ディレクトリにするがありますまた operationid パラメータのはの javascript ファイルのをしますこれはビジネスロジックをするですこのようにたちののんだはし API をさらにするためにすることができますオンラインでスワッガーをいめるをむスワッガーをいめる 3

6 2: スプリングフォックス Examples デフォルトのメッセージをきする Springfox はデフォルトですべての API コントローラにされるデフォルトのメッセージをしますこれにはえば Created と No Content さらにいくつかの 40x がまれますデフォルトのメッセージが API にされないがありますデフォルトのメッセージをにしてのメッセージをすることができますのメッセージをグローバルにすることができますデフォルトのメッセージのターン docket.usedefaultresponsemessages(false); 々のメッセージはコントローラごとにできます = message = "This is a bad request, please stick to the API description", response = message = "Your request cannot be authorized.", response = RestApiExceptionModel.class) ) のデフォルトメッセージをする ModelRef errormodel = new ModelRef("RestApiExceptionModel"); List<ResponseMessage> responsemessages = Arrays.asList( new ResponseMessageBuilder().code(401).message("Unauthorized").responseModel(errorModel).build(), new ResponseMessageBuilder().code(403).message("Forbidden").responseModel(errorModel).build(), new ResponseMessageBuilder().code(404).message("NotFound").responseModel(errorModel).build()); docket.globalresponsemessage(requestmethod.post, responsemessages).globalresponsemessage(requestmethod.put, responsemessages).globalresponsemessage(requestmethod.get, responsemessages).globalresponsemessage(requestmethod.delete, responsemessages); spring-boot で swagger-ui をして springfox をする 1. Maven または Gradle をしてアプリケーションに springfox をする 4

7 2. アプリケーションでしい Docket Bean をしそれをする 3. にじて API をする 4. アプリケーションをしされたをする 1 Maven で springfox をする pom.xml に swagger2 と swagger-ui のをする <dependency> <groupid>io.springfox</groupid> <artifactid>springfox-swagger2</artifactid> <version>2.6.0</version> </dependency> <dependency> <groupid>io.springfox</groupid> <artifactid>springfox-swagger-ui</artifactid> <version>2.6.0</version> </dependency> 2 スワッガーをするようにアプリケーションをするアノテーションきメインクラスにしこのまたはのコンフィグレーションクラスにスワッガー Docket Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build(); このではアプリケーションのすべてのSpring ControllerでAPIドキュメントがされます APIドキュメントのをのコントローラにするがあるはさまざまなRequestHandlerSelectorのからできますたとえば RequestHandlerSelectors.basePackage("your.package.structure") をする RequestHandlerSelectors.withClassAnnotation(Api.class) をしてをけたのクラスにづいてパッケージにづいて API ドキュメントをできます 3 あなたの API をするマニュアルにされているをしてコントローラのクラスとメソッドをでしてくださいなタイトルバージョンなど api のなをするには Docket bean の ApiInfoBuilder をしてください ApiInfoBuilder をしたメタデータの // Within your configuration class public static ApiInfo metadata(){ 5

8 return new ApiInfoBuilder().title("Your Title").description("Your Description").version("1.x").build(); // Within your method that definies the Docket bean... docket.apiinfo(metadata()); オンラインでスプリングフォックスをむスプリングフォックス 6

9 3: スワッガーユーあなたがのコンポーネントについてかなりののアイディアをっていればいいですね REST WS の JAX-RS アノテーションの Web アプリケーション REST APIMaven とその Examples ジャージー REST WS をつ swagger-ui Swaggerのウェブサイトによれば Swaggerはとコンピュータのがソースコードドキュメンテーションまたはネットワークトラフィックインスペクションにアクセスすることなくサービスのをしすることをにする REST APIにするのにしないインタフェースをすることです Swaggerをしてにするとはのロジックでリモートサービスをしできます Swaggerはレベルのプログラミングのためのインターフェースとにサービスをびすのをします Mavenとジャージをするとするとのをするがあります Maven Swagger DependencyとJAX-RS のは "maven webapp" をし webappのにこのurlにあるをりけるがあります webappのフォルダはプロジェクトにこれらのコンテンツをりけたのようになりますそののにいます 1. のようなのこのは " ApiOriginFilter.java " をつ java ファイルをします import javax.servlet.filterchain; import javax.servlet.filterconfig; import javax.servlet.servletexception; import javax.servlet.servletrequest; import javax.servlet.servletresponse; import javax.servlet.http.httpservletresponse; import java.io.ioexception; 7

10 public class ApiOriginFilter implements javax.servlet.filter { /** * dofilter public void dofilter(servletrequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletResponse res = (HttpServletResponse) response; res.addheader("access-control-allow-origin", "*"); res.addheader("access-control-allow-methods", "GET, POST, DELETE, PUT"); res.addheader("access-control-allow-headers", "Content-Type, api_key, Authorization"); chain.dofilter(request, response); /** * destroy public void destroy() { /** * init public void init(filterconfig filterconfig) throws ServletException { このファイルはクラスでされているをにフィルタリングします 2. このが " SwaggerJaxrsConfig.java " であるとしてののJavaファイルをのように SwaggerJaxrsConfig.java します import org.eclipse.persistence.jaxb.marshallerproperties; import org.eclipse.persistence.jaxb.beanvalidationmode; import org.glassfish.jersey.moxy.json.moxyjsonconfig; import org.glassfish.jersey.moxy.json.moxyjsonfeature; import org.glassfish.jersey.moxy.xml.moxyxmlfeature; import org.glassfish.jersey.server.resourceconfig; import org.glassfish.jersey.server.serverproperties; import org.glassfish.jersey.server.filter.rolesalloweddynamicfeature; import io.swagger.jaxrs.config.beanconfig; public class SwaggerJaxrsConfig extends ResourceConfig { public SwaggerJaxrsConfig() { BeanConfig beanconfig = new BeanConfig(); beanconfig.settitle("swagger API Title"); beanconfig.setversion("1.0.0"); beanconfig.setschemes(new String[] { "http" ); beanconfig.sethost("localhost:8080/swagger-ui"); beanconfig.setbasepath("/rest"); beanconfig.setresourcepackage( "your.restws.package"); beanconfig.setscan(true); property(serverproperties.bv_send_error_in_response, Boolean.TRUE); packages("your.restws.package"); 8

11 packages("io.swagger.jaxrs.listing"); register(moxyjsonfeature.class); // register(badrequestexceptionmapper.class); register(new MoxyJsonConfig().setFormattedOutput(true) // Turn off BV otherwise the entities on server would be validated by MOXy as well..property(marshallerproperties.bean_validation_mode, BeanValidationMode.NONE).resolver()); register(moxyxmlfeature.class); register(rolesalloweddynamicfeature.class); あなたがることができるようにのクラスでは々はこのプロジェクトはおみのベースパスをするとにホストされるどのホストのようにの UI をするためになすべてのとのようにサポートされているすべての HTTP プロトコルをしてい http か " https " そしてあなたのにじてよりなをしますまた Swagger にパッケージとに setresourcepackage をしてできる REST WS のをすべてらせるためのがあります web.xml に 2 つのファイルをしてのようにアプリケーションをサーバーにデプロイしたにするようにしてください <servlet> <servlet-name>jersey-servlet</servlet-name> <servlet-class>org.glassfish.jersey.servlet.servletcontainer</servlet-class> <init-param> <param-name>javax.ws.rs.application</param-name> <param-value>your.package.swaggerjaxrsconfig</param-value> </init-param> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>jersey-servlet</servlet-name> <url-pattern>/rest/*</url-pattern> </servlet-mapping> <filter> <filter-name>apioriginfilter</filter-name> <filter-class>your.package.apioriginfilter</filter-class> </filter> <filter-mapping> <filter-name>apioriginfilter</filter-name> <url-pattern>/rest/*</url-pattern> </filter-mapping> ここで Swagger でされるアノテーションをするのコードにしますのようにして Bean Employee.java をします import io.swagger.annotations.apimodel; import bean") public class Employee { private String name; 9

12 private String id; private String = "Name of employee", example = "Test Employee") public String getname() { return name; public void setname(string name) { this.name = = "Id of employee", example = "123456") public String getid() { return id; public void setid(string id) { this.id = = "Department of employee", example = "IT Division", allowablevalues = "IT, Sales, Admin") public String getdept() { return dept; public void setdept(string dept) { this.dept = dept; ここでしたSwaggerのコンポーネントはのとおりです bean") - Swagger UIにするがあるBeanクラスのをします ="ABC", example="deptname") - これは BeanでされるフィールドのをしますはフィールドのをしはそのフィールドのサンプルをしますここではのようにGET WebサービスをするためのRESTコントローラをします import javax.ws.rs.get; import javax.ws.rs.path; import javax.ws.rs.produces; import javax.ws.rs.core.genericentity; import javax.ws.rs.core.mediatype; import javax.ws.rs.core.response; import org.slf4j.logger; import org.slf4j.loggerfactory; import org.swagger.ws.bean.employee; import org.swagger.ws.service.employeeservice; import io.swagger.annotations.api; import io.swagger.annotations.apioperation; import io.swagger.annotations.apiresponse; import 10

13 @Api(tags = {"Employee") public class EmployeeController { private static final Logger LOGGER + value = "Fetch employee details", httpmethod="get", notes = "<br>this service fetches Employee details", response = = = 200,response = Employee.class, message = "Successful operation"),@apiresponse(code = 400, message = "Bad Request", response = = 422, message = "Invalid data", response = = 500, message = "Internal Server Error", response = Error.class) ) public Response getemployee() { EmployeeService employeeservice = new EmployeeService(); Employee empdetails = employeeservice.getemployee(); Response response; LOGGER.debug("Fetching employee"); GenericEntity<Employee> entity = new GenericEntity<Employee>(empDetails){; response = Response.status(200).entity(entity).build(); return response; ここでした Swagger のコンポーネントはのとおりです = {"Employee") - このアノテーションは Webサービスのタイトルとなるべきものを Swagger にしますこのタイトルは Employee ですタイトルのような Swagger ドキュメンテーションをいているは " GetEmployee " や " DeleteEmployee " のようにすべきではありません value = "Fetch employee details", httpmethod="get", notes = "<br>this service fetches Employee details", response = Employee.class) - このはあなたのwebserviceについて producesはのをし valueはウェブサービスにするなアイデアをする notesはこのWebサービスにするがされています = = 200,response = Employee.class, message = "Successful operation"),@apiresponse(code = 400, message = "Bad Request", response = = 422, message = "Invalid data", response = = 500, message = "Internal Server Error", response = Error.class) ) - このはこの Web サービスをしているにとしてけることができるさまざまなタイプの HTTP ステータスコードをしますこれによりエラーコードとそれにするカスタムメッセージをすることができますまたにじてのエラークラスでエラーをキャッチすることもできますに Web サービスがクライアントによってされたときにのをするの Service クラスをするがありますにじてすることができますデモのサンプルサービスはのとおりです public class EmployeeService { public Employee getemployee() { Employee employee = new Employee(); employee.setid("1"); employee.setname("test"); employee.setdept("it"); return employee; 11

14 これでSwagger UIにするドキュメントをるがいました SwaggerプロジェクトをしサーバーをしますすぐブラウザにきあなたのプロジェクトのURLをしてくださいこの http// localhost8080 / swagger-ui / スワッガーがしくされているのがされるはずですさてあなたの Web サービスのドキュメントをるにはのでることができるテキストボックスのプロジェクトの "base_url / rest / swagger.json" をしてくださいその URL をテキストボックスにすると REST Web サービスのドキュメントをするのがされます 12

15 のに api key とかれたテキストボックスではユーザ ID などにづいたのようなプロジェクトがなはのヘッダーやキーをできますそのためには <input placeholder="api_key"... まるタグので index.html をするもあります Swagger-UI のもう 1 つのは Try it out! というボタンがある Try it out! このボタンをするとこの Web サービスのがであるかをできますこのそのボタンをクリックするとでのようながされます 13

16 これは Swagger UI のサンプルデモですよりくのとそれらのをすることでドキュメントレベルでおいする REST コントローラをするにまだできるくのオプションがありますオンラインでスワッガーユーをむスワッガーユー 14

17 クレジット S. No Contributors 1 スワッガーをいめる Community, Daniel Käfer, gonephishing 2 スプリングフォックス mika 3 スワッガーユー Suyash 15

cocos2d-x #cocos2d-x

cocos2d-x #cocos2d-x 1 1: cocos2d-x 2 2 Examples 2 Mac OS X 2 2 2 2 Windows 3 3 3 4 8 You can share this PDF with anyone you feel could benefit from it, downloaded the latest version from: cocos2d-x It