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> <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>2,添加配置类
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; import springfox.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>