關於swagger文檔的使用方法

引言

最近在后台開發的時候，使用swagger2進行前后台接口文檔的聲明。由此遇見的一些問題，寫下來給自己復習。

參考：

https://blog.csdn.net/xupeng874395012/article/details/68946676

 

正文

在進行整合swagger2的時候，首先引入swagger2的jar，由於我使用的是springboot，所以以springboot為例。

<!--springboot 集成 swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.5.0</version>
</dependency>

引入swagger2的jar包之后，我們需要配置一個swagger2的配置類，來聲明一些swagger2的配置信息

這樣的話，swagger2就已經配置完畢了。接下來你只需要在你的接口上配置你想要顯示的信息即可。

 

@Configuration  //表示是配置類，要被加載
@EnableSwagger2 //swagger的配置
public class Swagger2 {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))  //添加ApiOperiation注解的被掃描
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        Contact contact = new Contact("xx", "www.baidu.com", "[e-mail]");
        return new ApiInfoBuilder()
                .title("cc").contact(contact).description("接口文檔").license("Apache License Version 2.0")
                .version("v1.0").build();
    }
}

接口上信息的配置如下：

@RestController
@Api(value = "user",  tags = "用戶模塊")
@RequestMapping("user")
public class UserController extends BaseController {

    @Resource
    private UserService userService;

    @ApiOperation(value = "用戶添加")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "user",value = "用戶" ,required = true,dataType = "String", paramType = "body")
    })
    @RequestMapping(value = "addUser",method = RequestMethod.POST)
    public ResultBean addUser(User user){
        return  resultBean;
    }
}

關於其中@Api和@ApiOperation等的詳細解釋如下：

作用范圍	API	使用位置
對象屬性	@ApiModelProperty	用於出入參數對象的字段上
協議集描述	@Api	用於Controller類上
協議描述	@ApiOperation	用在Controller的方法上
Response集	@ApiResponses	用在controller的方法上
Response	@ApiResponse	用在 @ApiResponses里邊
非對象參數集	@ApiImplicitParams	用在controller的方法上
非對象參數描述	@ApiImplicitParam	用在@ApiImplicitParams的方法里邊
描述返回對象的意義	@ApiModel	用在返回對象類上

 

關於參數的詳細解釋

屬性	取值	作用
paramType		查詢參數類型
	path	以地址的形式提交數據
	query	直接跟參數完成自動映射賦值
	body	以流的形式提交 僅支持POST
	header	參數在request headers 里邊提交
	form	以form表單的形式提交 僅支持POST
dataType		參數的數據類型 只作為標志說明，並沒有實際驗證
	Long
	String
name		接收參數名（必須與方法中參數名一致）
value		接收參數的意義描述（描述信息）
required		參數是否必填
	true	必填
	false	非必填
defaultValue		默認值