{"id":15091306,"url":"https://github.com/beomjunlee/restdocsandswagger","last_synced_at":"2026-01-04T22:41:31.808Z","repository":{"id":77569344,"uuid":"364473639","full_name":"BeomjunLee/RestDocsAndSwagger","owner":"BeomjunLee","description":":clipboard:Spring RestDocs + Swagger 조합 한번에 사용하기(OpenApi Spec):clipboard:","archived":false,"fork":false,"pushed_at":"2021-07-24T14:01:28.000Z","size":103,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-22T10:48:31.616Z","etag":null,"topics":["openapi-spec","restdocs","swagger-ui"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BeomjunLee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-05T05:45:58.000Z","updated_at":"2022-02-04T03:37:52.000Z","dependencies_parsed_at":"2023-03-12T01:02:49.346Z","dependency_job_id":null,"html_url":"https://github.com/BeomjunLee/RestDocsAndSwagger","commit_stats":{"total_commits":12,"total_committers":2,"mean_commits":6.0,"dds":"0.33333333333333337","last_synced_commit":"772d15bd29eb246a5be51ce7749499d168e8ef70"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeomjunLee%2FRestDocsAndSwagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeomjunLee%2FRestDocsAndSwagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeomjunLee%2FRestDocsAndSwagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeomjunLee%2FRestDocsAndSwagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BeomjunLee","download_url":"https://codeload.github.com/BeomjunLee/RestDocsAndSwagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244945590,"owners_count":20536296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openapi-spec","restdocs","swagger-ui"],"created_at":"2024-09-25T10:40:19.755Z","updated_at":"2026-01-04T22:41:31.734Z","avatar_url":"https://github.com/BeomjunLee.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"## RestDocs + Swagger (With OpenAPI-Spec)\n:clipboard:Spring RestDocs + Swagger 조합 한번에 사용하기(OpenApi Spec):clipboard:\n\n자세한 내용은 포스팅 하였으니 여기서 확인해주세요\nhttps://blog.naver.com/qjawnswkd/222340413113\u003cbr\u003e\n\n### Gradle Settings\n\n```java\nplugins {\n    ...\n    id \"org.asciidoctor.convert\" version \"1.5.9.2\"\n    id 'com.epages.restdocs-api-spec' version '0.11.3' //swagger 설정 1\n}\n\ndependencies {\n    ...\n    testCompile('com.epages:restdocs-api-spec-mockmvc:0.11.3') //swagger 설정2\n    asciidoctor 'org.springframework.restdocs:spring-restdocs-asciidoctor'\n    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'\n    ...\n}\n\next {\n    snippetsDir = file('build/generated-snippets')\n}\n\ntest {\n    outputs.dir snippetsDir\n    useJUnitPlatform()\n}\n\nasciidoctor {\n    inputs.dir snippetsDir\n    dependsOn test\n}\n\nbootJar {\n    dependsOn asciidoctor\n\n    copy{\n        from \"build/asciidoc/html5\"\n        into \"src/main/resources/static/docs/\"\n    }\n}\n\n//swagger 설정 3\nopenapi3 {\n    server = 'http://localhost:8080'\n    title = 'My API'\n    description = 'My API description'\n    version = '0.1.0'\n    format = 'yaml'\n\n    copy{\n        from \"build/api-spec\"\n        into \"src/main/resources/static/docs\"\n    }\n}\n\n```\n\u003cbr\u003e\n\n### Sample Test Code (OpenAPI-Spec Swagger)\n\n```java\n@Test\n@DisplayName(\"팔로잉 테스트\")\npublic void following() throws Exception{\n    //given\n    RequestUser requestUser = RequestUser.builder()\n            .username(\"test\")\n            .build();\n    userService.createUser(requestUser);\n    User user = userService.getUser(requestUser.getUsername());\n\n    //when\n    mockMvc.perform(post(\"/users/{id}/following\", user.getId())\n            .contentType(MediaType.APPLICATION_JSON)\n            .content(objectMapper.writeValueAsString(requestUser)))\n            .andDo(print())\n    //then\n            .andExpect(status().isOk())\n            .andExpect(jsonPath(\"resultCode\").value(ResultCode.OK.toString()))\n            .andExpect(jsonPath(\"status\").value(HttpStatus.OK.value()))\n            .andExpect(jsonPath(\"message\").value(\"팔로우 되었습니다\"))\n    //restDocs\n            .andDo(document(\"user-following\",\n                    pathParameters(\n                        parameterWithName(\"id\").description(\"사용자 고유 id\")\n                    ),\n                    requestFields(\n                            fieldWithPath(\"username\").description(\"유저 아이디\")\n                    ),\n                    responseFields(\n                            fieldWithPath(\"resultCode\").description(\"응답코드\"),\n                            fieldWithPath(\"status\").description(\"Http 상태코드\"),\n                            fieldWithPath(\"message\").description(\"응답 메세지\")\n                    )\n            ))\n   //Swagger 만 쓰면 pathParameters 와 request,response fields 가 restdocs 생성 안됨\n            .andDo(document(\"user-following\",\n                    preprocessRequest(prettyPrint()),\n                    preprocessResponse(prettyPrint()),\n                    resource(\n                            ResourceSnippetParameters.builder()\n                                    .description(\"다른 사용자를 팔로잉 할 수 있습니다\")\n                                    .summary(\"팔로잉 하기\")\n                                    .pathParameters(\n                                            parameterWithName(\"id\").description(\"사용자 고유 id\")\n                                    ).\n                                    requestFields(\n                                            fieldWithPath(\"username\").description(\"유저 아이디\")\n                                    ).\n                                    responseFields(\n                                            fieldWithPath(\"resultCode\").description(\"응답코드\"),\n                                            fieldWithPath(\"status\").description(\"Http 상태코드\"),\n                                            fieldWithPath(\"message\").description(\"응답 메세지\")\n                                    ).build()\n                    )\n            ));\n\n}\n```\n\n\u003cbr\u003e\n\n### Install \u0026 Run Swagger-UI with Docker\n\n```java\ndocker pull swaggerapi/swagger-ui\n\ndocker run -p 80:8080 swaggerapi/swagger-ui\n```\n\n### Result\n\n주소창에 서버상의 openapi3.yaml 파일 경로 입력\n\u003cimg src=\"https://user-images.githubusercontent.com/69130921/117283847-2d6cba00-aea1-11eb-99ae-85816745751f.png\"\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeomjunlee%2Frestdocsandswagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeomjunlee%2Frestdocsandswagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeomjunlee%2Frestdocsandswagger/lists"}