swagger #swagger

swagger #swagger

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

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 info@zzzprojects.com https://riptutorial.com/ja/home 1

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 https://riptutorial.com/ja/home 2

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

2: スプリングフォックス Examples デフォルトのメッセージをきする Springfox はデフォルトですべての API コントローラにされるデフォルトのメッセージをします これには えば 201 - Created と 204 - No Content さらにいくつかの 40x がまれます デフォルトのメッセージが API にされないがあります あなたはこれにするをみむがあります @ApiResponsesアノテーションをして デフォルトのメッセージをにしてのメッセージをすることができます のメッセージをグローバルにすることができます デフォルトのメッセージのターン docket.usedefaultresponsemessages(false); 々のメッセージは コントローラごとにできます えば @ApiResponses(value = { @ApiResponse(code=400, message = "This is a bad request, please stick to the API description", response = RestApiExceptionModel.class), @ApiResponse(code=401, 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 をする https://riptutorial.com/ja/home 4

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 スワッガーをするようにアプリケーションをする アノテーション @EnableSwagger2 を @SpringBootApplication アノテーションきメインクラスにし このまたはのコンフィグレーションクラスにスワッガー Docket Bean をします @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(){ https://riptutorial.com/ja/home 5

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

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; https://riptutorial.com/ja/home 7

public class ApiOriginFilter implements javax.servlet.filter { /** * dofilter */ @Override 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 */ @Override public void destroy() { /** * init */ @Override 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"); https://riptutorial.com/ja/home 8

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 io.swagger.annotations.apimodelproperty; @ApiModel("Employee bean") public class Employee { private String name; https://riptutorial.com/ja/home 9

private String id; private String dept; @ApiModelProperty(value = "Name of employee", example = "Test Employee") public String getname() { return name; public void setname(string name) { this.name = name; @ApiModelProperty(value = "Id of employee", example = "123456") public String getid() { return id; public void setid(string id) { this.id = id; @ApiModelProperty(value = "Department of employee", example = "IT Division", allowablevalues = "IT, Sales, Admin") public String getdept() { return dept; public void setdept(string dept) { this.dept = dept; ここでしたSwaggerのコンポーネントはのとおりです 1. @ApiModel("Employee bean") - Swagger UIにするがあるBeanクラスのをします 2. @ApiModelProperty(value ="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 io.swagger.annotations.apiresponses; @Path("/employee") https://riptutorial.com/ja/home 10

@Api(tags = {"Employee") public class EmployeeController { private static final Logger LOGGER = LoggerFactory.getLogger(EmployeeController.class); @GET @Produces(MediaType.APPLICATION_JSON + ";charset=utf-8") @ApiOperation(produces="application/json", value = "Fetch employee details", httpmethod="get", notes = "<br>this service fetches Employee details", response = Employee.class) @ApiResponses(value = { @ApiResponse(code = 200,response = Employee.class, message = "Successful operation"),@apiresponse(code = 400, message = "Bad Request", response = Error.class), @ApiResponse(code = 422, message = "Invalid data", response = Error.class), @ApiResponse(code = 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 のコンポーネントはのとおりです 1. @Api(tags = {"Employee") - このアノテーションは Webサービスのタイトルとなるべきも のを Swagger にします この タイトルは Employee です タイトルのような Swagger ド キュメンテーションをいているは " GetEmployee " や " DeleteEmployee " のようにすべきでは ありません 2. @ApiOperation(produces="application/json", value = "Fetch employee details", httpmethod="get", notes = "<br>this service fetches Employee details", response = Employee.class) - このは あなたのwebserviceについて producesはのをし valueはウェブサービスにするなアイデアをする notesは このWebサービスにするがされています 3. @ApiResponses(value = { @ApiResponse(code = 200,response = Employee.class, message = "Successful operation"),@apiresponse(code = 400, message = "Bad Request", response = Error.class), @ApiResponse(code = 422, message = "Invalid data", response = Error.class), @ApiResponse(code = 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; https://riptutorial.com/ja/home 11

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

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

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

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