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'

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>