5分鐘搞定Swagger2環境配置與使用

Maven配置

在pom.xml中加入依賴

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

與SpringMvc集成

增長JavaConfig配置文件

@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(buildApiInf())
        .host("localhost:8080")
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.dianping.orderdish.webapi"))//controller路徑
        .paths(PathSelectors.any()).build();
    }

    private ApiInfo buildApiInf() {
        return new ApiInfoBuilder()
        .title("RestAPI Docs")
        .termsOfServiceUrl("http://www.github.com/kongchen/swagger-maven-plugin")
        .build();

    }
}

若是Spring MVC代理了根路徑（\)的url，在spring-mvc.xml增長配置項。

<!-- Enables swgger ui-->
<mvc:default-servlet-handler/>
<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>

啓動Tomat，經過localhost:8080/swagger-ui.html訪問Swagger-UI。

Maven插件生成API描述文檔（json格式）

<plugin>
 <groupId>com.github.kongchen</groupId>
 <artifactId>swagger-maven-plugin</artifactId>
 <version>3.1.5</version>
 <configuration>
     <apiSources>
         <apiSource>
             <springmvc>true</springmvc>
             <locations>com.example.demo13</locations><!-- Controller所在的位置 -->
             <host>orderdish-ecom-web.51ping.com</host>
             <basePath>/s</basePath>
             <schemes>http,https</schemes>
             <info>
                 <title>${artifactId}</title>
                 <version>v1</version>
                 <description>Click Link Below for Help</description>
                 <termsOfService>http://www.github.com/kongchen/swagger-maven-plugin</termsOfService>
             </info>
             <!--html文檔輸出功能的模板文件 -->
             <!--<templatePath>${basedir}/src/test/resources/swagger_template/strapdown.html.hbs</templatePath>-->
             <!--html文檔輸出的位置 -->
             <!--<outputPath>${project.build.directory}/swagger-ui/swagger_document.html</outputPath>-->
             <swaggerDirectory>${project.build.directory}/swagger-ui</swaggerDirectory><!--定義API描述文檔的輸出目錄 -->
             <outputFormats>yaml,json</outputFormats><!--支持yaml和json格式 -->
         </apiSource>
     </apiSources>
 </configuration>
 <executions>
     <execution>
         <phase>compile</phase>
         <goals>
             <goal>generate</goal>
         </goals>
     </execution>
 </executions>
</plugin>

執行mvn complie，在設置的target目錄下會生成API描述文檔。

Maven插件生成靜態文檔（markdown格式）

<plugin>
 <groupId>io.github.swagger2markup</groupId>
 <artifactId>swagger2markup-maven-plugin</artifactId>
 <version>1.3.3</version>
 <configuration>
     <!--The URL or file path to the Swagger specification-->
     <swaggerInput>${project.build.directory}/swagger-ui/swagger.yaml</swaggerInput>
     <outputDir>${project.build.directory}/swagger-ui</outputDir>
     <outputFile>${project.build.directory}/swagger-ui/swagger.md</outputFile>
     <config>
         <!--設置輸出文件的語言：ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP-->
         <swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>
         <!--設置目錄的展示方式-->
         <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
     </config>
 </configuration>
 <executions>
     <execution>
         <phase>compile</phase>
         <goals>
             <goal>convertSwagger2markup</goal>
         </goals>
     </execution>
 </executions>
</plugin>

若是mvn complie時出現異常，多是由於以前生成的yaml不符合Swagger規範。把yaml複製到Swagger Editor中，根據提示的語法錯誤修正，再手動執行mvn swagger2markup:convertSwagger2markup便可生成markdown文檔。

Reference

1. swagger2markup文檔