SpringBoot使用Swagger创建在线接口文档

一、介绍

可以访问一下这个

Spring Boot整合swagger使用教程 - 随风行云 - 博客园 (cnblogs.com)

 

    Swagger 是为了方便用户在创建一个接口时，自动创建一个接口文档。

    优点：

自动生成文档，只需要在接口中使用注解进行标注（@ApiModel  @ApiParam）

自动更新文档，当接口被修改，文档也会自动对应修改

支持在线进行调试。

    缺点：

不能创建测试用例，如果需要对测试用例，可以使用postman。

规范问题

没有接口文档的更新管理，一个接口更新之后，可能不关心旧版的接口信息。

二、步骤：

    2.1  在maven中添加依赖：

<!--        swagger-->

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</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>

 

 

    2.2 进行swagger的配置

package com.qiang.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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**

* @author 
* @ClassName SwaggerConfig
* @description: 在线配置文档类
* @dtetime 2023年 06月 27日 15:55
* @version: 1.0
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2).
                pathMapping("/").select().
                apis(RequestHandlerSelectors.basePackage("com.qiang")).
                paths(PathSelectors.any()).
                build().apiInfo(new ApiInfoBuilder().title("SpringBoot整合Swagger").
                description("上班拿去用吧").
               version("1.0").
                contact(new Contact("qiang","http://www.qiang.com","forhappiness19@163.com"))
               .license("The Apache license").
                        licenseUrl("http://www.qiang.com").build());  }
}

 

 

    2.3 进行控制器（模拟接口）的配置

@RestController
@Api(tags = "这是一个swagger的一个简单的项目组")
public class SwaggerController {
 
    @GetMapping("/get")
    @ApiOperation(value = "第一个测试" ,notes = "第一个测试的note")
    public String get(){
        return "aaa";
    }

    @GetMapping("/list")
    @ApiOperation(value = "第二个测试" ,notes = "第二个测试的note")
    public String list(String id){
        return "第二个测试 "+id;
    }
}

      2.4访问http://localhost:端口号/swagger-ui.html

 三。常用注解：

@Api： 用于类，标识这个类是swagger的资源

@ApiIgnore： 用于类，忽略该 Controller，指不对当前类做扫描

@ApiOperation： 用于方法，描述 Controller类中的 method接口

@ApiParam： 用于参数，单个参数描述，与 @ApiImplicitParam不同的是，他是写在参数左侧的。如（ @ApiParam(name="username",value="用户名")Stringusername）

@ApiModel： 用于类，表示对类进行说明，用于参数用实体类接收

@ApiProperty：用于方法，字段，表示对model属性的说明或者数据操作更改

@ApiImplicitParam： 用于方法，表示单独的请求参数

@ApiImplicitParams： 用于方法，包含多个 @ApiImplicitParam

@ApiResponse： 用于方法，描述单个出参信息

@ApiResponses： 用于方法，包含多个@ApiResponse

@ApiError： 用于方法，接口错误所返回的信息