# springboot-swagger2-demo

**Repository Path**: dgatiger/springboot-swagger2-demo

## Basic Information

- **Project Name**: springboot-swagger2-demo
- **Description**: springboot 2.2.7集成swagger2.9.2，并生成markdown格式API文档
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2020-05-10
- **Last Updated**: 2021-01-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Swagger 2.9.2 Demo

### 1.关键操作
* 添加依赖
```xml
 <!--        swagger2 依赖开始-->
        <!--  https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <!-- 解决进入swagger页面报类型转换错误，排除2.9.2中的引用，手动增加1.5.21以上版本，这里选1.6.0版本-->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.6.0</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.swagger/swagger-models -->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.6.0</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.swagger/swagger-core -->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-core</artifactId>
            <version>1.6.0</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

        <!--swagger2markup用的到-->
        <!-- https://mvnrepository.com/artifact/org.pegdown/pegdown -->
        <dependency>
            <groupId>org.pegdown</groupId>
            <artifactId>pegdown</artifactId>
            <version>1.6.0</version>
            <scope>test</scope>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.github.swagger2markup/swagger2markup
        可能有两个包无法自动导入，需要手工处理，见本文第7小节
        -->
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.3</version>
        </dependency>
        <!--        swagger2 依赖结束-->
```
* application.yml加入swagger开关
```xml
swagger:
  enable: true
```
* 编写配置类
config/Swagger2Config.java
```java
package com.example.swagger2.config;

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author alexhu
 */
@EnableSwagger2
@Configuration
@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("功能测试")
                //创建人
                .contact(new Contact("Alex Hu", "www.example.com", "email@example.com"))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}
```
* 控制器类加注解，关键@Api/@ApiOperation/@ApiParam三个
controller/ExampleController.java
```java
package com.example.swagger2.controller;

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author alexhu
 */
@Api(tags = "样例Controller",value = "控制器Demo")
@RestController
public class ExampleController {

    @ApiOperation(value = "回显name",httpMethod = "GET")
    @GetMapping("/echo/{name}")
    public String echoName(@ApiParam(name = "name", value = "名字", required = true) @PathVariable("name") String name) {
        return "Echo " + name;
    }

    @ApiOperation(value = "问候name",httpMethod = "GET")
    @GetMapping("/hello")
    public String helloName(@ApiParam(name = "name", value = "名字", required = true) @RequestParam("name") String name) {
        return "Hello " + name;
    }
}
```
* 编写测试代码，生成full-api-doc.md
```java
package com.example.swagger2;

import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;

import java.net.URL;
import java.nio.file.Paths;

@RunWith(SpringRunner.class)
@SpringBootTest
public class SwaggerTo {
    /**
     * 生成Markdown格式文档,并汇总成一个文件
     * @throws Exception
     */
    @Test
    public void generateMarkdownDocsToFile() throws Exception {
        //    输出Markdown到单文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("./docs/full-api-doc"));
    }
}
```
* 启动项目，访问
```shell script
http://localhost:8080/swagger-ui.html
```
### 2.常见问题--两个包无法导入
在这里 如果通过maven不能download这两个jar的同学可以去下载这两个jar   
https://mvnrepository.com/artifact/nl.jworks.markdown_to_asciidoc/markdown_to_asciidoc/1.0  
https://mvnrepository.com/artifact/ch.netzwerg/paleo-core/0.11.0  
下载jar后本地安装到本地仓库：
```shell script
mvn install:install-file -Dfile=~/Downloads/markdown_to_asciidoc-1.1.jar -DgroupId=nl.jworks.markdown_to_asciidoc -DartifactId=markdown_to_asciidoc -Dversion=1.0 -Dpackaging=jar
mvn install:install-file -Dfile=~/Downloads/paleo-core-0.14.0.jar -DgroupId=ch.netzwerg -DartifactId=paleo-core -Dversion=0.11.0 -Dpackaging=jar
```
脚本中是升级了，用新版本当旧版本用

### 3.参考链接
1. https://blog.csdn.net/qq_40592377/article/details/89520847
2. https://blog.csdn.net/jiangshuanshuan/article/details/84325692
3. https://www.freesion.com/article/8284174476/