Spring boot 整合 swagger生成api文件(轉換成markdown格式)
阿新 • • 發佈:2018-11-19
spring boot 整合 swagger
步驟
1. 匯入jar包
2. 新增配置類
3. 新增介面類
3. 啟動伺服器
4. 訪問UI頁面,可線上測試介面
5. 匯出swagger原始檔
6. 轉換成markdown格式檔案
1,匯入jar包
gradle方式
compile 'io.springfox:springfox-swagger2:2.6.1'
compile 'io.springfox:springfox-swagger-ui:2.6.1'
3,新增介面類(主要看註解,參照官網)
4,啟動伺服器
5,訪問UI頁面
http://localhost:8080/swagger-ui.html
訪問http://localhost:8080/v2/api-docs可以得到json資料
訪問http://editor.swagger.io/可以將json資料轉換成yaml檔案並下載到本地
轉換成markdown格式檔案
2.新增轉換類
步驟
1. 匯入jar包
2. 新增配置類
3. 新增介面類
3. 啟動伺服器
4. 訪問UI頁面,可線上測試介面
5. 匯出swagger原始檔
6. 轉換成markdown格式檔案
1,匯入jar包
gradle方式
compile 'io.springfox:springfox-swagger2:2.6.1'
compile 'io.springfox:springfox-swagger-ui:2.6.1'
maven方式
<dependency> <groupId>io.springfox</groupId>2,新增配置類<artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>
import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; importspringfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * @author hanxu * @ClassName swagger2 * @Description * @date 2017-07-10 22:12:31 */ @Configuration @EnableSwagger2 public class Swagger2Config { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.zxg.qgg")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("ZXG-線上API文件") .description("杭州紙箱哥廣告傳媒有限公司") .termsOfServiceUrl("http://www.zhixiangge.com/") .version("1.0") .build(); } }
3,新增介面類(主要看註解,參照官網)
@ApiOperation(value = "根據分類id分頁查詢文章") @ApiImplicitParams({ @ApiImplicitParam(name = "articleId", value = "分類id", required = true, dataType = "Long", paramType = "query"), @ApiImplicitParam(name = "pageNum", value = "pageNum", required = true, dataType = "Long", paramType = "query"), @ApiImplicitParam(name = "pageSize", value = "pageSize", required = true, dataType = "Long", paramType = "query") }) @GetMapping("list") public R queryAll(@RequestParam Map<String, Object> params) { return R.ok().data(cmsArticlePageInfo); }
4,啟動伺服器
5,訪問UI頁面
http://localhost:8080/swagger-ui.html
訪問http://localhost:8080/v2/api-docs可以得到json資料
訪問http://editor.swagger.io/可以將json資料轉換成yaml檔案並下載到本地
轉換成markdown格式檔案
1.匯入jar包
gradle方式
compile 'io.github.swagger2markup:swagger2markup:1.3.1'
maven方式
<dependency> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup</artifactId> <version>1.3.1</version> </dependency>
2.新增轉換類
public static void main(String[] args) throws Exception { Path outputFile = Paths.get("build/swagger"); Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.MARKDOWN) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter converter = Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs")) .withConfig(config) .build(); converter.toFile(outputFile); }
3.排除jar包衝突(匯入了swagger的兩個jar包後再匯入轉markdown的jar包,其中有個swagger-models會有問題,要排除一下)
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> <exclusions> <exclusion> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> </exclusion> </exclusions> </dependency>