Swagger自动生成api文档

Swagger是什么

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档
Swagger 是一套围绕 Open API 规范构建的开源工具，可以帮助设计，构建，记录和使用 REST API
Swagger 工具有：

1. Swagger Editor ：基于浏览器编辑器，可以在里面编写 Open API
   规范。类似 Markdown 具有实时预览描述文件的功能
2. Swagger UI：将 Open API 规范呈现为交互式 API 文档。用可视化
   UI 展示描述文件。
3. Swagger Codegen：将 OpenAPI 规范生成为服务器存根和客户端
   库。通过 Swagger Codegen 可以将描述文件生成 html 格式和 cwiki 形
   式的接口文档，同时也可以生成多种言语的客户端和服务端代码。
4. Swagger Inspector：和 Swagger UI 有点类似，但是可以返回更多
   信息，也会保存请求的实际参数数据。
5. Swagger Hub：集成了上面所有项目的各个功能，你可以以项目
   和版本为单位，将你的描述文件上传到 Swagger Hub 中。在 Swagger
   Hub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收
   费版

Swagger底层原理

使用 Swagger，就是把相关的信息存储在它定义的描述文件里面（yml 或 json 格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码

使用方式

1修改pom文件

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

2启动类中加入注解@EnableSwagger2

3加入SpringFoxConfig.java

在项目的controller、service等包的同级目录下建立一个config包，并写入如下文件

package com.imooc.mall.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;

@Configuration
public class SpringFoxConfig {

    //访问http://localhost:8083/swagger-ui.html可以看到API文档
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("项目web的名字")
                .description("描述")
                .termsOfServiceUrl("")
                .build();
    }
}

4加入WebMvcConfig.java文件

在项目的controller、service等包的同级目录下建立一个config包，并写入如下文件

package com.imooc.mall.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
 * 描述：     配置地址映射
 */
@Configuration
public class ImoocMallWebMvcConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations(
                "classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations(
                "classpath:/META-INF/resources/webjars/");
    }
}

5 给Web 服务的接口加注解

接口上方加入@ApiOperation
添加web接口描述

访问可视化页面

地址：http://localhost:8082/swagger-ui.html

详细介绍见文档：08 SpringBoot与MybatisPlus\03\Swagger.pdf