项目接口文档-Swagger的使用

Swagger使用

在前后端分离项目中，后端开发人员需要为前端开发人员提供接口信息，接口过多或接口修改时，信息文档书写变得困难，而swagger可以解决这些问题，通过些简单配置就可以自动生成接口文档，并且会动态更新。

springboot整合swagger

1.pom.xml引入swagger依赖（springfox）

		<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

2.启动类中开启Swagger（@EnableOpenApi）

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;

@EnableOpenApi//开启Swagger3
@SpringBootApplication//指明这是一个spring boot应用
public class Application {

    public static void main(String[] args) {
        //用于从main方法中启动spring应用的类
        SpringApplication.run(Application.class, args);
    }
}

3.在接口上添加说明性注解

全部注解信息： https://www.cnblogs.com/three-fighter/p/12346184.html

@Api(tags = "管理员管理接口")
@RestController
public class ManageAdminController {
    @ApiOperation("用户修改接口")
    @ApiImplicitParams({//请求信息
            @ApiImplicitParam(name = "a", value = "参数a"),
            @ApiImplicitParam(name = "b", value = "参数b"),
            @ApiImplicitParam(name = "c", value = "参数c"),
            @ApiImplicitParam(name = "d", value = "d为必选参数 ", required = true),
    })
    @ApiResponses({ //响应信息
            @ApiResponse(code = 200, message = "操作成功状态码"),
    })
    //修改用户
    @PostMapping("/test")
    public Map test(@RequestParam Map<String, Object> remap) {
    	Map map=new HashMap();
    	map.put("status",200);
    	map.put("msg","操作成功!");
    	return map;
    }
}

4.访问swagger文档（需启动服务）

访问 http://localhost:8088/swagger-ui/

点击可查看详细信息

5.作者说明配置(自由选择)

import io.swagger.annotations.ApiOperation;
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;

@Configuration
public class Swagger3Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("更多请咨询服务开发者jun665")
                .contact(new Contact("jun665", "#", "2476545423@qq.com"))
                .version("1.0")
                .build();
    }
}

请求、响应 封装的处理

请求、响应参数的封装类中需要注释的字段必须有getter方法才能显示参数信息。

1.请求封装model

@Data
public class ValidateSignDTO implements Serializable {

    @ApiModelProperty(value = "昵称 ",required=true)
    private String name;
    
    @ApiModelProperty(value = "密码",required=true)
    private String password;
    
    @ApiModelProperty(value = "邮箱",required=true)
    private String email;
}

2.响应封装类

@Getter
public class CommonResult<T>{

    @ApiModelProperty(value = "状态码" )
    private long returnCode;
    
    @ApiModelProperty(value = "提示信息")
    private String returnMessage;
    
    @ApiModelProperty(value = "响应数据")
    private T bean;
    ......
}

增强方案knife4j

knife4j提供了更为友好的界面支持，增加接口排序、Swagger资源保护、导出Markdown、参数缓存众多强大功能，用法与swagger相比基本上没变。

详情请参考我的另一篇博文：https://blog.csdn.net/qq_52681418/article/details/112602084