SpringBoot(集成swagger2构建RESTful API文档)

https://mp.weixin.qq.com/s?__biz=MzU3NDYzMDQ5NA==&tempkey=OTYzX2UzZGRTY3RpclRMZW9zZHhHa0V4S0gwYXRzOE1ub1kyUE9rLW16MXAzb3Uwa2lySVJLdElpMFd0YkQySmVYT0ZrcExVajZueXl0YVdET0k1VGNub2R4RlM1RUhEcjh0MV9QM19ucjNPTkdtOFNReDhXYlFMUFUzdFJfNVNZYlpFZ2o1aHFoRFViX0JpVU8wOXZ2QUJIbU5zdzl4RmdQSnYwSDl2NHd%2Bfg%3D%3D&chksm=7d2e3ea14a59b7b76057529b6aa5037cfa2355532390a79d328c24dbcb607c4dd8b71d32a356&mpshare=1&scene=1&srcid=0701XeAFZifoozex6l1NfzZ2#wechat_redirect

01

引入依赖

SpringBoot

    在创建一个简单的springboot项目后，首先要引入swagger的Maven依赖。

    

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 <modelVersion>4.0.0modelVersion>
 <groupId>com.springboot.learninggroupId>
 <artifactId>springboot-swaggerartifactId>
 <version>0.0.1-SNAPSHOTversion>

 <description>springboot集成swagger2构建RESTful APIdescription>
 <developers>
   <developer>
     <name>wangxiaojiename>
     <email>[email protected]email>
   developer>
 developers>

 
 <dependencies>
   <dependency>
     <groupId>org.springframework.bootgroupId>
     <artifactId>spring-boot-starter-parentartifactId>
     <version>1.5.4.RELEASEversion>
     <type>pomtype>
   dependency>
   <dependency>
     <groupId>org.springframework.bootgroupId>
     <artifactId>spring-boot-starter-webartifactId>
     <version>1.5.4.RELEASEversion>
   dependency>
   
   <dependency>
     <groupId>io.springfoxgroupId>
     <artifactId>springfox-swagger2artifactId>
     <version>2.2.2version>
   dependency>

   <dependency>
     <groupId>io.springfoxgroupId>
     <artifactId>springfox-swagger-uiartifactId>
     <version>2.2.2version>
   dependency>

 dependencies>
project>

02

创建Swagger2的配置类

SpringBoot

在SpringBoot启动类的同级目录下创建Swagger2的配置类。

Swagger2配置类的具体信息如下：

package com.springboot;

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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2 {
 @Bean
 public Docket creatRestApi() {
   return new Docket(DocumentationType.SWAGGER_2)
       .apiInfo(apiInfo())
       .select()
       .apis(RequestHandlerSelectors
           .basePackage("com.springboot.swagger"))
       .paths(PathSelectors.any()).build();
 }

 private ApiInfo apiInfo() {
   return new ApiInfoBuilder()
       .title("Spring Boot中使用Swagger2构建RESTful APIs")
       .description("更多文章请关注: 微信公众号：JavaCola ")
       .termsOfServiceUrl("https://github.com/AbsolutelyEmpty")
       .contact("大大蜡笔小小新").version("1.0").build();
 }
}

03

添加文档内容

SpringBoot

以上所有完成后，其实可以通过http://localhost:8080/swagger-ui.html访问接口文档。

但是这样的接口文档描述并不是很友好，基本都是基于方法名，Controller的类命名生成的，所以要通过注解对接口文档进行更为友好的提示与说明，需要在对应的接口方法上添加注解。

package com.springboot.swagger;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.springboot.model.CityModel;
@Api(value="城市信息管理服务")
@RequestMapping(value="/cities")
@RestController
public class CityController {
 Map<String, Object>  map = new HashMap<String, Object>();
 CityModel cityModel = new CityModel("71000","西安","二线","9983平方公里");
 List cityInfoList = new ArrayList();
 {  
   String postCode = "71000";
   map.put(postCode, cityModel);
 }
 @ApiOperation(value = "查询城市信息",notes = "通过邮政编码查询对应城市信息")
 @ApiImplicitParam(name = "postCode",value = "所查询城市的邮政编码",required = true, dataType = "String", paramType="path")
 @GetMapping(value = "/findCityInfo/{postCode}")
 public CityModel findCityInfo(@PathVariable String postCode){
   CityModel cityModel =(CityModel) map.get(postCode);
   return cityModel;
 }
 @ApiOperation(value = "添加城市信息",notes = "添加城市信息")
 @ApiImplicitParam(name = "cityModelInfo",value = "所添加城市的具体信息",required = true, dataType = "CityModel", paramType="body")
 @ApiResponse(code = 200, message = "添加成功")
 @PostMapping(value = "/addCityInfo")
 public String addCityInfo(@RequestBody CityModel cityModelInfo){
   cityInfoList.add(cityModelInfo);
   return "SUCCESS";
 }
 @ApiOperation(value = "更新城市信息",notes = "根据邮政编码更新城市信息")
 @ApiImplicitParams({
   @ApiImplicitParam(name = "postCode", value = "邮政编码",required = true, dataType = "String", paramType = "path" ),
   @ApiImplicitParam(name = "cityModel",value = "所添加城市的具体信息",required = true, dataType = "CityModel", paramType="body")})
 @PutMapping(value = "/updateCityInfo/{postCode}/cityInfo")
 public CityModel updateCityInfo(@PathVariable String postCode,@RequestBody CityModel cityModel){
   CityModel cityUpdateModel =(CityModel) map.get(postCode);
   cityUpdateModel.setCityLevel("一线");
   return cityUpdateModel;
 }
 @ApiOperation(value = "删除城市信息",notes = "通过邮政编码删除对应城市信息")
 @ApiImplicitParam(name = "postCode",value = "所删除城市的邮政编码",required = true, dataType = "String", paramType="path")
 @ApiResponse(code = 200, message = "删除成功")
 @DeleteMapping(value = "/deleteCityInfo/{postCode}")
 public String deleteCityInfo(@PathVariable String postCode){
   cityInfoList.add(cityModel);
   cityInfoList.remove(0);
   return "SUCCESS";
 }
}

注：其他的文档说明的注解很简单，基本自己可以学习一下。

这里需要说明的是@ApiImplicitParama中的paramType属性，具体的值对应如下：

• qurery：对应@RequestParam的参数；

• header：对应头部信息的参数；

• path：对应url中的参数；

• body：对应@RequestBody中的参数。

再次访问文档的访问地址：

http://localhost:8080/swagger-ui.html,

结果图如下，是不是更加简单明白。