Swagger 最全使用教程

概述：

我的理解是通过注解的方式生成接口文档。
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。它可以在修改代码的同时同步修改接口文档，一个最大的优点是能实时同步api与文档。别的不多说，开始教程！！！

Begin

添加依赖

		<!-- swagger jar -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- swagger-ui jar -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

第一个是用于API文档的生成，第二个是用于展示文档的UI界面

配置

直接上代码，代码里有说明：

package com.swagger.demo.config;

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 Shuoshi.Yan
 * @package:com.swagger.demo.config
 * @className:swagger配置类
 * @description:
 * @date 2019-12-04 15:23
 * @version:V1.0
 * @NOTICE：本内容仅限于xxx有限公司内部传阅,禁止外泄以及用于其他的商业项目
 * @ Copyright  xxx. All rights reserved.
 **/
@Configuration
//开启swagger
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        //版本类型是swagger2
        return new Docket(DocumentationType.SWAGGER_2)
                //通过调用自定义方法apiInfo，获得文档的主要信息
                .apiInfo(apiInfo())
                .select()//通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现
                .apis(RequestHandlerSelectors.basePackage("com.swagger.demo.controller"))//扫描该包下面的API注解
                .paths(PathSelectors.any())
                .build();
    }
    //API相关信其他息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口服务文档") //接口管理文档首页显示
                .description("接口服务文档")//API的描述
               // .termsOfServiceUrl("www.baidu.com")//网站url等
                .version("1.0")
                .build();
    }
}

然后看一下配置文件：

server.port=9090
server.servlet.context-path=/swagger
#启用swagger
swagger.enable=true

在这里启动swagger，在生产环境中需要禁用，设置程false

controller层

package com.swagger.demo.controller;

import com.swagger.demo.io.CityIO;
import com.swagger.demo.result.CityResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

/**
 * @author Shuoshi.Yan
 * @package:com.swagger.demo.test
 * @className:
 * @description:
 * @date 2019-12-04 10:39
 * @version:V1.0
 * @NOTICE：本内容仅限于xxx有限公司内部传阅,禁止外泄以及用于其他的商业项目
 * @ Copyright  xxx. All rights reserved.
 **/
@RestController
@RequestMapping("/yss")
@Api(tags = "城市",description = "城市")
public class SwaggerController {

    @GetMapping("/get")
    @ApiOperation(value = "根据id查询城市名称",notes = "根据id查询城市名称",response = String.class)
    public String getTest(@ApiParam(name = "城市id",value = "id",required = false) @RequestParam(value = "id",required = false)String id){
        return "this is BeiJing！";
    }

    @PostMapping("/post")
    @ApiOperation(value = "城市简介",notes = "城市简介",response = CityResult.class)
    public CityResult postTest(@ApiParam(required = true) @RequestBody CityIO cityIO){
        CityResult cityResult = new CityResult();
        return cityResult;
    }
}

CityIO

package com.swagger.demo.io;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * @author Shuoshi.Yan
 * @package:com.swagger.demo
 * @className:
 * @description:
 * @date 2019-12-04 15:55
 * @version:V1.0
 * @NOTICE：本内容仅限于xxx有限公司内部传阅,禁止外泄以及用于其他的商业项目
 * @ Copyright  xxx. All rights reserved.
 **/
@Data
@ApiModel(value = "CityIO参数说明",description = "CityIO参数说明")
public class CityIO {
    @ApiModelProperty(value = "城市id")
    private String id;
    @ApiModelProperty(value = "城市位于南方北方 1/南方 2/北方")
    private String position;
}

一些注解说明

对这些常用的注解及元素说明，具体的其他元素可以查看源码。

• @Api：用在类上
  - tags：描述类的用途
  - description：注释说明这个类
  - 其实tags和description这俩都差不多都是对这个类的说明
  
  

• @ApiOperation：用在方法上
  - value：字段说明
  - notes：注释说明
  - response：方法的返回类型
  
  

• @ApiParam：用在参数上
  - name：参数名称
  - required：是否必传
  

• @ApiModel：用在入参或回参的对象类上
  - value：对这个类进行说明
  - description：说明这个类
  - 和@Api的tags/description一样，都是起说明作用
  

• @ApiModelProperty：用在对象类中的变量上
  - value：对这个字段的说明
  - example：字段举例
  

• @EnableSwagger2：配置swagger时启用swagger
  
  到这里，就可以在代码中简单使用swagger，访问地址(http://localhost:9090/swagger/swagger-ui.html),但是作为励志成为技术大牛的菜鸟，这点那肯定是不能够满足我的，既然知道了使用，那么swagger时怎么导出的呢，这是个大问题，在这里我在网上学习了两种方式进行导出，分别问使用maven和代码方式，但是使用maven导出的时候频频出错，没办法我只有自己找问题改代码了，代码中可能有待优化的部分，不喜勿怪!

生成并导出文档

这里提供导出两种格式：html和pdf，对了还有本身的adoc格式
直接上代码：

方式一：代码方式

package com.swagger.demo;

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.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;

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

@SpringBootTest
class DemoApplicationTests {
	//这里是你访问的swagger地址的/v2/api-docs地址，直接把swagger后面改成/v2/api-docs就行了
    private static final String url = "http://localhost:9090/swagger/v2/api-docs";

    //生成AsciiDocs格式文档
    @Test
    public void generateAsciiDocs() throws Exception {
        //    输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL(url))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("src/docs/asciidoc/adoc"));
    }
    //生成Markdown格式文档
    @Test
    public void generateMarkdownDocsToFiles() throws Exception {
        //    输出Markdown到单文件
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL(url))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("src/docs/asciidoc/mark"));
    }
    //生成AsciiDocs格式文档,并汇总成一个文件
    @Test
    void contextLoads() throws MalformedURLException {
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .build();

        Swagger2MarkupConverter.from(new URL(url))
                .withConfig(config)
                .build()
                .toFile(Paths.get("src/docs/asciidoc/adocs"));
        System.out.println(System.getProperty("user.dir"));
    }

    //生成Markdown格式文档,并汇总成一个文件
    @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(url))
                .withConfig(config)
                .build()
                .toFile(Paths.get("src/docs/asciidoc/mark"));
    }

}

在这里我比较喜欢最后两个，因为只生成一个文档，方便快捷。说一下我在这里出现的错误：Paths.get("src/docs/asciidoc/adocs")
这个路径是你的导出路径，其实我是不想写这个问题的，但是想想还是写吧，错误谁没犯过，贼尴尬；在这里不要写成"/src"，不要加"/"，不要加"/"，不要加"/"，加了之后就找不到文件夹了，导致导不出来。

System.getProperty("user.dir")
这个是输出当前路径的，可以直接忽略、略过

方式二：

在pom.xml中进行配置：
代码：

1. 在中添加如下配置

<!--导出接口文档-->
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.1</version>
        </dependency>

2. 在中添加插件配置，需要添加两个，先说第一个
   Number.1

 <!-- swagger接口导出第一步必须确认系统的 /v2/api-docs 接口可用  -->
            <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.3.1</version>
                <configuration>
                    <!-- api-docs访问url -->
                    <swaggerInput>http://localhost:9090/swagger/v2/api-docs</swaggerInput>
                    <!-- 生成为单个文档，输出路径 最后一个/asciidoc 为文件名不是路径-->
                    <outputFile>src/docs/asciidoc/asciidoc</outputFile>
                    <!-- 生成为多个文档，输出路径 -->
                    <!--<outputDir>src/docs/asciidoc</outputDir>-->
                    <config>
                        <!-- 输出文件语言：wiki格式文档 -->
                        <!--<swagger2markup.markupLanguage>CONFLUENCE_MARKUP</swagger2markup.markupLanguage> -->
                        <!-- 输出文件语言：ascii格式文档 -->
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                        <!-- 输出文件语言：markdown格式文档 -->
                        <!--<swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>-->
                        <!--目录的展现方式-->
                        <!--<swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>-->
                    </config>
                </configuration>
            </plugin>

具体说明代码里有。总的来说这个配置是导出swagger本身的adoc文件的，adoc文件时生成html和pdf文件的关键，html和pdf都是在adoc的基础上生成的，生成此文件的命令：mvn swagger2markup:convertSwagger2markup
还有 和这两个控制生成是控制这个项目只生成一个总的文件，还是每个类都生成一个文件，在你想转换生成是单个还是多个文件时候要重新启动项目并重新调用mvn swagger2markup:convertSwagger2markup命令,在后面会具体说明操作流程，各位莫急。

Number.2
第二个是html和pdf插件的配置

 <!--生成HTML和PDF的插件-->
            <!--  命令 mvn asciidoctor:process-asciidoc -->
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>

                <!--pdf-->
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctorj-pdf</artifactId>
                        <version>1.5.0-alpha.10.1</version>
                    </dependency>
                    <dependency>
                        <groupId>org.jruby</groupId>
                        <artifactId>jruby-complete</artifactId>
                        <version>1.7.21</version>
                    </dependency>
                </dependencies>
                <!--html-->
                <configuration>
                    <!--需要生成格式的文件位置-->
                    <sourceDirectory>src/docs/asciidoc</sourceDirectory>
                    <!--生成格式文件的存放位置-->
                    <outputDirectory>src/docs/html</outputDirectory>
                    <!--生成文件的格式-->
                    <backend>html</backend>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <!--菜单栏在左边-->
                        <toc>left</toc>
                    </attributes>
                </configuration>
                <!--pdf-->
                <!--<configuration>-->
                    <!--<sourceDirectory>src/docs/asciidoc</sourceDirectory>-->
                    <!--<outputDirectory>src/docs/pdf</outputDirectory>-->
                    <!--<backend>pdf</backend>-->
                    <!--<sourceHighlighter>coderay</sourceHighlighter>-->
                    <!--<attributes>-->
                        <!--<toc>left</toc>-->
                    <!--</attributes>-->
                <!--</configuration>-->
            </plugin>

在这里是把生成html格式的注释掉了，若你想生成html只需要注释掉pdf并打开html就哦了
具体说一下
src/docs/asciidoc这个是adoc的位置，不要设置错了，如果设置错误了导不出来文档，你就一行一行找代码吧
好了，接下来开始生成，激动人心的时刻到了：

方式一操作说明

方式一没啥操作说明，真的，相信我，点击运行就哦了。
为啥要写这个菜单呢，主要是因为直接写"方法二的操作说明"你没感觉到很是突兀吗，所以没办法只能写一个"方式一操作说明"

方式二操作说明

1. 首先在项目的根目录打开cmd：我截了个图，怕有的同行不知道在哪里
2. 
   就在这里打开cmd
3. 输入mvn swagger2markup:convertSwagger2markup命令回车
   
   如果看到这个绿绿的SUCCESS 那么恭喜你最关键的一步生成adoc成功了
   到项目中看一下就有了adoc文件：
   
4. 我用的是idea开发工具，我就使用idea说明接下来的流程了，打开：Terminal 一般情况下是在左下角
   
5. 输入命令 ```mvn asciidoctor:process-asciidoc`` 这个命令就是最后一步，生成html或pdf
   
   如果看见绿绿的SUCCESS 再一次恭喜你swagger生成文档你~学会了
   我的生成文件：
   
   若想需要完整项目可以进行下载：
   https://download.csdn.net/download/y368769/12014989

感谢支持!!!