IT 接口后端：足迹第十七步Restful请求格式(如何使用Swagger自动生成接口的说明文档)

本文档介绍了如何通过在Spring Boot项目中集成Swagger来创建符合Restful风格的API，并自动生成接口说明文档。主要步骤包括添加pom依赖，启用Swagger2注解，配置Swagger类，控制器类的注解设置，以及遵循Restful请求规范（GET用于查询，POST用于添加）。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

1.pom

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

2.Application类里加注解@EnableSwagger2

package com.sugon;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
@MapperScan("com.sugon.mapper")
public class Application extends WebMvcConfigurerAdapter {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    // 解决跨域
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowCredentials(true)
                .allowedHeaders("*")
                .allowedOrigins("*")
                .allowedMethods("*");
    }
}

3.swagger配置类

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

/**
 * swagger-ui的配置
 */
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sugon.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("RESTful APIs")
                .description("接口文档")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }

}

4.controller类注解

package com.sugon.controller;

import com.github.pagehelper.PageInfo;
import com.sugon.entity.DeptEntity;
import com.sugon.service.DeptService;
import com.sugon.util.ResultStatus;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/api")
@Api(tags = "部门信息")
public class DeptController {

    @Autowired
    private DeptService deptService;

    @GetMapping("/deptList")
    @ApiOperation(value = "获取部门列表", notes = "获取所有数据")
    public ResponseEntity<Object> deptList(@RequestBody(required = false) DeptEntity deptEntity) {
        PageInfo<DeptEntity> list = deptService.getDeptList(deptEntity);
        return new ResponseEntity<>(list, HttpStatus.OK);
    }

    @PostMapping("/deptInfo")
    @ApiOperation(value = "添加部门", notes = "添加数据")
    public ResponseEntity<ResultStatus> addDept(@RequestBody DeptEntity deptEntity) {
        ResultStatus resultStatus = deptService.insertDept(deptEntity);
        return new ResponseEntity<ResultStatus>(resultStatus, HttpStatus.OK);
    }

    @PutMapping("/deptInfo")
    @ApiOperation(value = "更新部门信息", notes = "更新数据")
    public ResponseEntity<ResultStatus> updateDept(@RequestBody DeptEntity deptEntity) {
        ResultStatus resultStatus = deptService.updateDept(deptEntity);
        return new ResponseEntity<ResultStatus>(resultStatus, HttpStatus.OK);
    }

    @GetMapping("/deptInfo/{ids}")
    @ApiOperation(value = "批量删除部门", notes = "批量删除")
    public ResponseEntity<ResultStatus> deleteDeptByIds(@PathVariable("ids") List<Integer> ids) {
        ResultStatus resultStatus = deptService.delete(ids);
        return new ResponseEntity<ResultStatus>(resultStatus, HttpStatus.OK);
    }
}

5.界面：符合Rest建议风格的代码叫Restful；

1）Rest约定：查询GET请求，添加用POST请求；

2）Swagger定义：是专用于接口对接的说明文档生成工具；