차이

문서의 선택한 두 판 사이의 차이를 보여줍니다.

--- programming:documentation:swagger [2018/07/12 08:38]
kwon37xi
+++ programming:documentation:swagger [2023/08/17 15:39] (현재)
kwon37xi [ReDoc]
@@ 줄 1: / 줄 1: @@
 ====== Swagger ======
   * http://swagger.io/
+  * [[programming:documentation:swagger:codegen|Swagger Code Generation]]
+  * -> [[programming:documentation:openapi_spec|Open API Specification]]로 표준화됨.
+  * [[springframework:springfox|SpringFox]] - Spring & Swagger
   * [[https://github.com/swagger-api/swagger-core/wiki/Annotations|Swagger Annotations]]
   * [[https://dzone.com/articles/why-is-swagger-json-better-than-swagger-java-clien|Why Is Swagger JSON Better Than Swagger Java Client? - DZone Java]]
-===== Spring MVC and swagger =====
+===== ReDoc =====
-  * [[https://github.com/martypitt/swagger-springmvc|Swagger SpringMVC]]
+  * [[https://github.com/Rebilly/ReDoc|ReDoc]] : Swagger API 문서화.
-  * [[https://github.com/adrianbk/swagger-springmvc-demo/tree/master/swagger-ui|Swagger-UI]]
+  * [[https://webhookrelay.com/blog/2018/11/05/openapi-redoc-tutorial/|Documenting your API with OpenAPI (Swagger) and Redoc — Web Relay]]
-  * Spring MVC Swagger 튜토리얼 시리즈
+  * 페이지 내 검색과 더 유려한 UI를 제공해줌.
-    * [[http://www.javacodegeeks.com/2014/10/spring-rest-api-with-swagger-creating-documentation.html|Spring Rest API with Swagger – Creating documentation Swagger 문서 생성]]
-    * [[http://www.javacodegeeks.com/2014/11/spring-rest-api-with-swagger-exposing-documentation.html|Spring Rest API with Swagger – Exposing documentation]] Spring REST API를 웹 서비스로 볼 수 있게 해줌
-  * Spring MVC API 적용 Servlet의 "/"가 아닌 "/api/*" 형태로 매핑되면 Swagger 적용이 복잡해진다.<code java>
+===== Swagger2MarkUp =====
-// /css/*, /js/* 등에 대한 핸들러 추가.
+  * [[https://github.com/Swagger2Markup/swagger2markup|Swagger2Markup/swagger2markup]] A Swagger to AsciiDoc or Markdown converter to simplify the generation of an up-to-date RESTful API documentation by combining documentation that’s been hand-written with auto-generated API documentation.
-@Override
+  * [[https://github.com/Swagger2Markup/swagger2markup-gradle-plugin|Swagger2Markup/swagger2markup-gradle-plugin]] A Swagger2Markup Gradle Plugin.
-protected void addResourceHandlers(ResourceHandlerRegistry registry) {
+  * [[https://github.com/Swagger2Markup/spring-swagger2markup-demo|Swagger2Markup/spring-swagger2markup-demo]] [[springframework:springfox|SpringFox]] 로 Spring Boot 문서를 test 시에 ''swagger.json'' 으로 생성하고, 이를 가지고 [[:asciidoc|AsciiDoc]]을 생성한뒤 [[asciidoc:asciidoctor|AsciiDoctor]] 를 통해서 다시 HTML/PDF 문서로 바꾼다.
-  registry.addResourceHandler("css/**", "js/**", "lib/**", "images/**", "swagger-ui.js")
+  * [[https://dzone.com/articles/static-api-documentation-with-spring-and-swagger|Static API Documentation With Spring and Swagger - DZone Integration]]
-    .addResourceLocations(WEB_JAR_RESOURCE_LOCATION,
+<code java>
-        WEB_JAR_RESOURCE_LOCATION + "css/",
+// Spring / Swagger 에서 swagger.json 을 파일로 뽑아내는 예제
-        WEB_JAR_RESOURCE_LOCATION + "js/",
-        WEB_JAR_RESOURCE_LOCATION + "lib/",
+@WebAppConfiguration
-        WEB_JAR_RESOURCE_LOCATION + "images/")
+@RunWith(SpringJUnit4ClassRunner.class)
-    .setCachePeriod(0);
+@AutoConfigureRestDocs(outputDir = "build/asciidoc/snippets")
-  super.addResourceHandlers(registry);
+@SpringBootTest(classes = {Application.class, SwaggerConfig.class})
-}
+@AutoConfigureMockMvc
+public class Swagger2MarkupTest {
+    private static final Logger LOG = LoggerFactory.getLogger(Swagger2MarkupTest.class);
+    @Autowired
+    private MockMvc mockMvc;
-@ApiIgnore
+...
-@Controller
-public class SwaggerController {
-  @Autowired
-    private ResourceLoader resourceLoader;
-  @RequestMapping("/swagger")
+    @Test
-    public void swagger(HttpServletResponse response) throws IOException {
+    public void createSpringfoxSwaggerJson() throws Exception {
-      final Resource swaggerHtmlResource =
+        //String designFirstSwaggerLocation = Swagger2MarkupTest.class.getResource("/swagger.yaml").getPath();
-        resourceLoader.getResource("classpath:/META-INF/resources/sdoc.jsp");
-      final String swaggerHtmlContents =
+        String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
-        CoupangIOUtils.toString(swaggerHtmlResource.getInputStream(), "UTF-8");
+        MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
-      final String refinedHtml = swaggerHtmlContents
+                .accept(MediaType.APPLICATION_JSON))
-        .replaceAll("http://swagger.wordnik.com", "/api/swagger");
+                .andExpect(status().isOk())
+                .andReturn();
-      response.setContentType("text/html; charset=UTF-8");
+        MockHttpServletResponse response = mvcResult.getResponse();
-      final PrintWriter writer = response.getWriter();
+        String swaggerJson = response.getContentAsString();
-      writer.write(refinedHtml);
+        Files.createDirectories(Paths.get(outputDir));
-      writer.close();
+        try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)){
+            writer.write(swaggerJson);
+        }
     }
+...
 }
 </code>
+===== 기타 =====
+  * https://github.com/sourcey/spectacle
+  * [[https://www.baeldung.com/swagger-generate-pdf|Generate PDF from Swagger API Documentation | Baeldung]]

권남

사용자 도구

사이트 도구

차이

문서 도구