OpenAPI Specification
- OpenAPI Specification
- Swagger
- What Is the Difference Between Swagger and OpenAPI?
- SpringFox
- SpringDoc - SpringFramework Open API Specification
- Spring REST Docs
- Spring REST Docs with Swagger
- Links
OpenAPI Specification
OpenAPI 또는 OpenAPI Specification(OAS) 는 Swagger 에서 발전한 API 명세 형태를 의미한다.
Document Structure
It is RECOMMENDED that the root OpenAPI document be named: openapi.json or openapi.yaml.
Swagger
What is Swagger ? Swagger 란 Open Api Specification(OAS)를 위한 프레임워크이다.
Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs.
Swagger does this by asking your API to return a YAML or JSON that contains a detailed description of your entire API. This file is essentially a resource listing of your API which adheres to OpenAPI Specification.
- Related Articles
Check swagger.io/open-source-integrations for a list of tools that let you generate Swagger from code.
ReDoc
- ReDoc
- Generate interactive API documentation from OpenAPI definitions
- Redoc is an open-source tool for generating documentation from OpenAPI (fka Swagger) definitions.
- Live Demo
- Documenting your API with OpenAPI (Swagger) and Redoc — Web Relay
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
- Swagger2Markup/swagger2markup-gradle-plugin
- Swagger2Markup/spring-swagger2markup-demo: SpringFox 로 Spring Boot 문서를 test 시에 swagger.json 으로 생성하고, 이를 가지고 AsciiDoc을 생성한뒤 AsciiDoctor 를 통해서 다시 HTML/PDF 문서로 바꾼다.
- Static API Documentation With Spring and Swagger - DZone
Swagger Code Generation
- Related Articles
- Swagger Codegen Document
- swagger-api/swagger-codegen: swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.
- Generate Spring Boot Project with Swagger - Baeldung
- gigaSproule/swagger-gradle-plugin
- int128/gradle-swagger-generator-plugin
What Is the Difference Between Swagger and OpenAPI?
- What Is the Difference Between Swagger and OpenAPI?
- OpenAPI = Specification
- Swagger = Tools for implementing the specification
OpenAPI 는 RESTful API 설계를 위한 업계 표준 사양을 나타내고 Swagger 는 SmartBear 도구 세트를 의미.
SpringFox
- Swagger 3.x 를 사용하려면 springfox-boot-starter Dependency 만 추가하면 됨
Philosophically, we want to discourage using (swagger-core) annotations that are not material to the service description at runtime.
- Related Articles
- Spring Boot 2.6.0 / Spring fox 3 - Failed to start bean documentationPluginsBootstrapper
SpringDoc - SpringFramework Open API Specification
OpenAPI 3 어노테이션 없이, Spring MVC/WebFlux 어노테이션을 인식하여 자동으로 OpenAPI Spec 3 문서 생성.
springdoc-openapi java library helps to automate the generation of API documentation using spring boot projects. springdoc-openapi works by examining an application at runtime to infer API semantics based on spring configurations, class structure and various annotations.
Automatically generates documentation in JSON/YAML and HTML format APIs. This documentation can be completed by comments using swagger-api annotations.
- Related Articles
Spring REST Docs
Spring REST Docs 는 테스트 코드 기반으로 RESTful 문서생성을 돕는 도구로 기본적으로 Asciidoctor 를 사용하여 HTML 를 생성한다. Spring MVC 테스트 프레임워크로 생성된 snippet 을 사용해서 올바르지 않으면 생성된 테스트가 실패하여 정확성을 보장해준다.
Rest Docs 는 테스트 코드 기반으로 문서가 작성되기 때문에 문서와 실제 코드의 일치성이 높고 테스트 코드로 문서가 표현되기 때문에 Production 코드에 어떠한 코드(Ex. 문서 관련 Annotation) 추가도 필요가 없다는 장점이 있다.
- RelatedArticles
Spring REST Docs with Swagger
- RelatedArticles