在pom.xml中加入依賴html
<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>
增長JavaConfig配置文件java
@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
增長配置項。git
<!-- 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。github
<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描述文檔。web
<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文檔。spring