Spring Boot 集成 Swagger生成接口文档

目的：

1. Swagger是什么

2. Swagger的优点

3. Swagger的使用

 

---

Swagger是什么

官网（https://swagger.io/）

　　Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步，其实也就是 前后端开发人员联系的纽带 ——swagger就是一款让你更好的书写API文档的框架。　

　　swagger根据你的代码的改变也会自动改变生成接口

---

Swagger的优点

1. - Swagger Spec 是一个规范。

2. - Swagger Api 是 Swagger Spec 规范 的一个实现，它支持 jax-rs, restlet, jersey 等等。

3. - Springfox libraries 是 Swagger Spec 规范 的另一个实现，专注于 spring 生态系统。

4. - Swagger.js and Swagger-ui 是 javascript 的客户端库，能消费该规范。

5. - springfox-swagger-ui 仅仅是以一种方便的方式封装了 swagger-ui ，使得 Spring 服务可以提供服务。

 

---

 

Swagger的使用

　　添加关于swagger的pom依赖

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

SwaggerController

只有在类上使用@Api注解标注并且在方法上使用@ApiOperation注解才会暴露给swagger，

这种方式没有包名的限制，可以将需要暴露的接口分散到各个包里，不使用这两个注解就不会暴露

对象属性                        @ApiModelProperty                用在参数对象的字段上

协议集描述                    @Api                                        用在Conntroller类上

协议描述                        @ApiOperation                        用在controller方法上

Response集                   @ApiResponses                      用在controller方法上

Response                      @ApiResponse                        用在@ApiResponses里面

非对象参数集                 @ApilmplicitParams                用在controller方法上

 

paramType：表示参数放在哪个地方
    header-->请求参数的获取：@RequestHeader(代码中接收注解)
    query-->请求参数的获取：@RequestParam(代码中接收注解)
    path（用于restful接口）-->请求参数的获取：@PathVariable(代码中接收注解)
    body-->请求参数的获取：@RequestBody(代码中接收注解)
    form（不常用）

package com.ht.swagger.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * 这是一个测试类，所以这里是用注解开发接口去测试swagger
 */
@Api(description = "测试接口")  //使用位置，用来标识Class
@RestController
public class swaggerController {
    @ApiOperation(value = "测试")  //接口说明，这里相当于编写了个名字
    @PostMapping("/test")   //这里是用来post提交
    public String index(){
        return "本是青灯不归客";  //返回的数据
    }
}

 

启动类SwaggerApplication

package com.ht.swagger;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;
import org.springframework.scheduling.annotation.EnableScheduling;

@EnableScheduling
@SpringBootApplication(scanBasePackages = "com",exclude = { DataSourceAutoConfiguration.class })  //这里相当于访问了com包下所有类，并且关闭它访问数据源的渠道
public class SwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }

}

exclude = { DataSourceAutoConfiguration.class }  //设置可以不用访问数据库数据也可以启动成功

如果不添加上述所说的代码，就会报下面这个错

 

 

 

启动成功：

 去浏览器中访问  http://localhost:8080/swagger-ui.html

 

 就可以看到进入swagger成功

看我返回的数据和生成的接口文档

 

 

如果页面报404的错的话

　　加入这个类

package com.ht.swagger.controller;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Component
public class WebMvcConfig implements WebMvcConfigurer {
 
    /**
     * 添加静态资源文件，外部可以直接访问地址
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
 
}

 

谢谢观看！！！