一、添加依赖
<!--swagger--> <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>
二、创建配置类
import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; 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; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class Swagger2Config { /** * 创建API应用 * apiInfo() 增加API相关信息 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现, * 本例采用指定扫描的包路径来定义指定要建立API的目录。 * * @return */ @Bean public Docket webApiConfig(){ return new Docket(DocumentationType.SWAGGER_2) .groupName("webApi") .apiInfo(webApiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.juhaowl.education.controller")) .build(); } /** * 创建该API的基本信息(这些基本信息会展现在文档页面中) * 访问地址:http://项目实际地址/swagger-ui.html * @return */ private ApiInfo webApiInfo(){ return new ApiInfoBuilder() .title("句号网络-讲师管理API文档") .description("本文档描述了讲师管理微服务接口定义") .version("1.0") .contact(new Contact("Park", "http://juhaowl.com", "747423188@qq.com")) .build(); } }
三、在controller上添加注解
import com.juhaowl.framework.demain.education.EduTeacher; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import java.util.List; /** * Created by Park on 2020-3-30. */ @Api(value = "讲师管理接口" ,tags = {"讲师管理"}) public interface EduTeacherControllerApi { @ApiOperation(value ="讲师列表查询" ) public List<EduTeacher> list(); @ApiOperation(value = "根据ID逻辑删除对应讲师") public boolean delete(String id); }
注解说明
- @Api:用在类上,说明该类的作用。
- @ApiOperation:注解来给API增加方法说明。
- @ApiImplicitParams : 用在方法上包含一组参数说明。
- @ApiImplicitParam:用来注解来给方法入参增加说明。
- @ApiResponses:用于表示一组响应
- @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
- @ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
- @ApiModelProperty:描述一个model的属性
其中
@ApiResponse参数:
- code:数字,如400
- message:信息,如“参数填写错误”
- response:抛出异常的类
@ApiImplicitParam参数: - paramTpye:指定参数放在哪些地方(header/query/path/body/form)
- name:参数名
- dataTpye:参数类型
- required:是否必输(true/false)
- value:说明参数的意思
- defaultValue:参数默认值