SpringBoot整合Swagger2，搭建Restful API在线文档

Myth丶恋晨 2023-08-17 17:35 132阅读 0赞

Swagger是一个功能强大的在线API文档框架，目前它的版本是2.x，所以称为Swagger2。Swagger2提供了在线文档的查阅和测试功能。下面看看怎么在SpringBoot中集成Swagger2。

##### 1、引入依赖 #####

在pom文件引入下面的依赖

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

##### 2、配置Swagger2 #####

写一个配置类，加上相关的注解，代码如下

@Configuration
    @EnableSwagger2
    public class Swagger2 {
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.codeliu.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("SpringBoot利用swagger构建api文档")
                    .description("欢迎关注公众号【秃头哥编程】")
                    .version("1.0")
                    .build();
        }
    }

其中@Configuration注解表示这是一个配置类，@EnableSwagger2开启Swagger2的功能。在配置类中需要注入一个Docket的Bean，该Bean包含了apiInfo，即基本的API文件的描述信息，以及包扫描的基本包名等信息。

##### 3、生成文档的注解 #####

Swagger2通过注解来生成API接口文档，文档信息包括接口名、请求方法、参数、返回信息等。通常情况下用于生成在线API文档，下面是常见的注解：

*  @Api：修饰整个类，用于描述Controller。
 *  @ApiOperation：描述类的方法，或者说一个接口。
 *  @ApiParam：单个参数描述。
 *  @ApiModel：用对象来接收参数。
 *  @ApiProperty：用对象接收参数时，描述一个对象的字段。
 *  @ApiResponse：HTTP响应的一个描述。
 *  @ApiResponses：HTTP响应的整体描述。
 *  @ApiIgnore：Swagger2忽略该api。
 *  @ApiError：发生错误返回的信息。
 *  @ApiParamImplicit：一个请求参数。
 *  @ApiParamsImplicit：多个请求参数。

##### 4、编写dao层代码 #####

@Mapper
    public interface GarbageSearchMapper {
    
        GarbageSearch findGarbageByName(String name);
    
        List<GarbageSearch> findAll();
    
        Integer addGarbage(GarbageSearch garbageSearch);
    
        Integer updateGarbage(GarbageSearch garbageSearch);
    
        Integer deleteGarbage(Integer id);
    }

上面就是一些普通的增删改查。

##### 5、编写Service层代码 #####

构建一组RESTful风格的API接口。

@Service
    public class GarbageSearchServiceImpl implements GarbageSearchService {
    
        @Autowired
        private GarbageSearchMapper garbageSearchMapper;
    
        public GarbageSearch findGarbageByName(String name) {
            return garbageSearchMapper.findGarbageByName(name);
        }
    
        public List<GarbageSearch> findAll() {
            return garbageSearchMapper.findAll();
        }
    
        public Integer addGarbage(GarbageSearch garbageSearch) {
            return garbageSearchMapper.addGarbage(garbageSearch);
        }
    
        public Integer updateGarbage(GarbageSearch garbageSearch) {
            return garbageSearchMapper.updateGarbage(garbageSearch);
        }
    
        public Integer deleteGarbage(Integer id) {
            return garbageSearchMapper.deleteGarbage(id);
        }
    }

##### 6、Web层 #####

在该层通过Get、Post、Delete、Put这四种Http方法，构建一组RESTful风格的API。

@RestController
    @RequestMapping("/garbage/search")
    public class GarbageSearchController {
    
        @Autowired
        private GarbageSearchService garbageSearchService;
    
        @ApiOperation(value = "垃圾列表", notes = "获取所有垃圾")
        @GetMapping(value = {""})
        public List<GarbageSearch> getGarbages() {
            List<GarbageSearch> garbages = garbageSearchService.findAll();
            return garbages;
        }
    
        @ApiOperation(value = "增加垃圾", notes = "增加一条垃圾搜索记录")
        @PostMapping(value = "")
        public Integer postGarbage(@RequestBody GarbageSearch garbageSearch) {
            return garbageSearchService.addGarbage(garbageSearch);
        }
    
        @ApiOperation(value = "删除垃圾搜索记录", notes = "根据垃圾的id删除垃圾搜索记录")
        @DeleteMapping(value = "/{id}")
        public Integer deleteGarbage(@PathVariable Integer id) {
            return garbageSearchService.deleteGarbage(id);
        }
    
        @ApiOperation(value = "更新信息", notes = "根据指定的id更新垃圾搜索记录")
        @PutMapping(value = "/{id}")
        public Integer putGarbage(@PathVariable Integer id, @RequestBody GarbageSearch garbageSearch) {
            GarbageSearch garbageSearch1 = new GarbageSearch();
            garbageSearch1.setGarbageSearchCount(garbageSearch.getGarbageSearchCount() + 1);
            garbageSearch1.setGarbageSearchId(id);
    
            return garbageSearchService.updateGarbage(garbageSearch);
        }
    
        @ApiIgnore
        @GetMapping(value = "/hi")
        public String test() {
            return "hello world";
        }
    }

通过@ApiOperation注解描述生成在线文档的具体API的说明，其中value值为该接口的名称，note为该接口的详细文档说明。这样就可以让Swagger2生成在线的API接口文档了，如果不需要某接口生成文档，只需要加上@ApiIgnore注解即可。

启动项目，输入http://localhost:\{项目端口号\}/swagger-ui.html，浏览器就会生成接口文档。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FfaGVsbG93b3Jk_size_16_color_FFFFFF_t_70]  
点开接口，还可以看到详细信息包括参数和返回值、错误码等信息。

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FfaGVsbG93b3Jk_size_16_color_FFFFFF_t_70 1]

##### 欢迎关注公众号【秃头哥编程】，领取海量编程资源，还有项目源码免费领取。 #####

![在这里插入图片描述][20191001214425125.png]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FfaGVsbG93b3Jk_size_16_color_FFFFFF_t_70]: /images/20230808/c12b7bfc97744940a4bbdbbae0b876a4.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FfaGVsbG93b3Jk_size_16_color_FFFFFF_t_70 1]: /images/20230808/e763cbb640294e3ba2642eb70bc40335.png
[20191001214425125.png]: /images/20230808/92726290336a40e58cb6ddc81d38bb6c.png