Swagger使用詳解

一、Swagger是什麼

Swagger是一組開源項目，在ActiveMatrix SOA Suite的一個子項目中開始，期望極大地減少RESTful Web服務開發的時間。其目標是簡化API的設計、文檔、測試和部署過程。

Swagger通過基於Swagger規範自動生成文檔，包括界面測試工具。在設計API的時候，你可以使用Swagger UI來預覽你所定義的API，這意味著你的API在實現之前就可以與團隊共享和討論。此外，Swagger還提供了依靠已定義API自動生成客戶端代碼的強大工具。Swagger使API開發過程更容易，更快捷。

二、Swagger核心概念

1. Swagger UI

Swagger UI提供了一個互動式文檔框架，可以讓我們非常輕鬆的展示和測試API。這個文檔框架的結構表示了我們的API的資源，操作和參數。
要使用Swagger UI，我們需要使用簡單的HTML文件和OpenAPI規範，只需要幾個步驟就能展示和交互訪問API。

2. Swagger Editer

Swagger Editor是一個在線編輯器，允許您編寫和測試Swagger規範。它具有語法高亮，實時解析和文檔預覽功能。Swagger Editor使我們能夠在編寫介面規範時實現最佳實踐並快速迭代開發。

3. Swagger Codegen

Swagger Codegen可以通過API定義生成API客戶端代碼，根據您的模板將API定義轉換為客戶端庫文檔甚至伺服器端的 stubs。Codegen支持超過50多種語言（包括Java，C＃，Python，PHP，Ruby等）。

4. Swagger Core

Swagger Core是一個Java和Scala庫，可以根據OpenAPI規範生成API文檔。Swagger Core還可以將自動生成的文檔與JAX-RS，Servlet和Jersey等API進行集成。

三、Swagger使用示例

1. 環境準備

首先，我們需要一個Web容器，例如Tomcat、WebLogic、Jboss等。我以Tomcat為例，以及Maven用於管理依賴。

2. 依賴配置

我們需要導入Swagger的核心包及Swagger UI界麵包，下面是Maven配置：

    
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
    

3. 配置Swagger

Swagger需要一個配置類來提供Swagger UI界面訪問路徑和Swagger API文檔的配置路徑。

    
        @Configuration
        @EnableSwagger2
        public class SwaggerConfiguration {

            @Bean
            public Docket docket() {
                return new Docket(DocumentationType.SWAGGER_2)
                        .pathMapping("/")
                        .apiInfo(apiInfo())
                        .select()
                        .apis(RequestHandlerSelectors.basePackage("com.demo.controller"))
                        .paths(PathSelectors.any())
                        .build();
            }

            private ApiInfo apiInfo() {
                return new ApiInfoBuilder()
                        .title("Demo API")
                        .description("Demo REST API")
                        .version("1.0.0")
                        .build();
            }

        }
    

4. 添加Swagger UI

最後，我們需要把Swagger添加到Web應用程序中。我們可以在應用的Servlet中添加一個Swagger靜態資源處理器，它將所有的Swagger UI資源映射到一個URI中。

    
        @Configuration
        public class WebMvcConfiguration implements WebMvcConfigurer {
            @Override
            public void addResourceHandlers(ResourceHandlerRegistry registry) {
                registry.addResourceHandler("swagger-ui.html")
                        .addResourceLocations("classpath:/META-INF/resources/");
                registry.addResourceHandler("/webjars/**")
                        .addResourceLocations("classpath:/META-INF/resources/webjars/");
            }
        }
    

5. 測試Swagger

啟動Tomcat容器，瀏覽器上輸入：http://localhost:8080/swagger-ui.html，你將看到Swagger UI和Demo API的文檔，可以在這裡嘗試調用API介面。

結語

Swagger提供了一種顯然，易於使用的方法來開發API文檔和測試。藉助Swagger，API文檔的編寫變得更加容易，不再需要使用繁瑣而易錯的手動編寫方法。更重要的是，Swagger秉承著RESTful設計實踐，極大的提升了API的可讀性、可維護性和可拓展性。