[TOC] # 依赖 ~~~ <!-- swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency> ~~~ # 常用注解 ~~~ Api：修饰整个类，描述Controller的作用 ApiOperation：描述一个类的一个方法，或者说一个接口 ApiParam：单个参数描述 ApiModel：用对象来接收参数 ApiProperty：用对象接收参数时，描述对象的一个字段 ApiResponse：HTTP响应其中1个描述 ApiResponses：HTTP响应整体描述 ApiIgnore：使用该注解忽略这个API ApiError ：发生错误返回的信息 ApiImplicitParam：一个请求参数 ApiImplicitParams：多个请求参数 ~~~ ## Api标记 默认情况,只会扫描具有@Api注解的类 Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式： ~~~ @Api(value = "/user", description = "Operations about user") ~~~ 与Controller注解并列使用。 属性配置： | 属性名称 | 备注 | | --- | --- | | value | url的路径值 | | tags | 如果设置这个值、value的值会被覆盖 | | description | 对api资源的描述 | | basePath | 基本路径可以不配置 | | position | 如果配置多个Api 想改变显示的顺序位置 | | produces | For example, "application/json, application/xml" | | consumes | For example, "application/json, application/xml" | | protocols | Possible values: http, https, ws, wss. | | authorizations | 高级特性认证时配置 | | hidden | 配置为true 将在文档中隐藏 | 在SpringMvc中的配置如下： ~~~ @Controller @RequestMapping(value = "/api/pet", produces = {APPLICATION_JSON_VALUE, APPLICATION_XML_VALUE}) @Api(value = "/pet", description = "Operations about pets") public class PetController { } ~~~ ~~~ @Api(value = "消息" ,description = "用户接口", protocols = "http") @RestController @RequestMapping("user") public class UserController { ~~~  ## ApiOperation标记 ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义,使用方式： ~~~ @ApiOperation( value = "Find purchase order by ID", notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions", response = Order, tags = {"Pet Store"}) ~~~ 与Controller中的方法并列使用。 属性配置： | 属性名称 | 备注 | | --- | --- | | value | url的路径值 | | tags | 如果设置这个值、value的值会被覆盖 | | description | 对api资源的描述 | | basePath | 基本路径可以不配置 | | position | 如果配置多个Api 想改变显示的顺序位置 | | produces | For example, "application/json, application/xml" | | consumes | For example, "application/json, application/xml" | | protocols | Possible values: http, https, ws, wss. | | authorizations | 高级特性认证时配置 | | hidden | 配置为true 将在文档中隐藏 | | response | 返回的对象 | | responseContainer | 这些对象是有效的 "List", "Set" or "Map".，其他无效 | | httpMethod | "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH" | | code | http的状态码 默认 200 | | extensions | 扩展属性 | 在SpringMvc中的配置如下： ~~~kotlin @RequestMapping(value = "/order/{orderId}", method = GET) @ApiOperation( value = "Find purchase order by ID", notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions", response = Order.class, tags = { "Pet Store" }) public ResponseEntity<Order> getOrderById(@PathVariable("orderId") String orderId) throws NotFoundException { Order order = storeData.get(Long.valueOf(orderId)); if (null != order) { return ok(order); } else { throw new NotFoundException(404, "Order not found"); } } ~~~ ## ApiParam标记 ApiParam请求属性,使用方式 ~~~kotlin public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true) User user) ~~~ 与Controller中的方法并列使用。 属性配置： | 属性名称 | 备注 | | --- | --- | | name | 属性名称 | | value | 属性值 | | defaultValue | 默认属性值 | | allowableValues | 可以不配置 | | required | 是否属性必填 | | access | 不过多描述 | | allowMultiple | 默认为false | | hidden | 隐藏该属性 | | example | 举例子 | 在SpringMvc中的配置如下： ~~~kotlin public ResponseEntity<Order> getOrderById( @ApiParam(value = "ID of pet that needs to be fetched", allowableValues = "range[1,5]", required = true) @PathVariable("orderId") String orderId) ~~~ ## ApiResponse ApiResponse：响应配置，使用方式： ~~~ @ApiResponse(code = 400, message = "Invalid user supplied") ~~~ 与Controller中的方法并列使用。 属性配置： | 属性名称 | 备注 | | --- | --- | | code | http的状态码 | | message | 描述 | | response | 默认响应类 Void | | reference | 参考ApiOperation中配置 | | responseHeaders | 参考 ResponseHeader 属性配置说明 | | responseContainer | 参考ApiOperation中配置 | 在SpringMvc中的配置如下： ~~~kotlin @RequestMapping(value = "/order", method = POST) @ApiOperation(value = "Place an order for a pet", response = Order.class) @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") }) public ResponseEntity<String> placeOrder( @ApiParam(value = "order placed for purchasing the pet", required = true) Order order) { storeData.add(order); return ok(""); } ~~~ ## ApiResponses ApiResponses：响应集配置，使用方式： ~~~ @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") }) ~~~ 与Controller中的方法并列使用。 属性配置： | 属性名称 | 备注 | | --- | --- | | value | 多个ApiResponse配置 | 在SpringMvc中的配置如下： ~~~kotlin @RequestMapping(value = "/order", method = POST) @ApiOperation(value = "Place an order for a pet", response = Order.class) @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") }) public ResponseEntity<String> placeOrder( @ApiParam(value = "order placed for purchasing the pet", required = true) Order order) { storeData.add(order); return ok(""); } ~~~ ## ResponseHeader > 响应头设置，使用方法 ~~~kotlin @ResponseHeader(name="head1",description="response head conf") ~~~ 与Controller中的方法并列使用。 属性配置： | 属性名称 | 备注 | | --- | --- | | name | 响应头名称 | | description | 头描述 | | response | 默认响应类 Void | | responseContainer | 参考ApiOperation中配置 | 在SpringMvc中的配置如下： ~~~ @ApiModel(description = "群组") ~~~ ## 其他 * @ApiImplicitParams：用在方法上包含一组参数说明； * @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面 * paramType：参数放在哪个地方 * name：参数代表的含义 * value：参数名称 * dataType： 参数类型，有String/int，无用 * required ： 是否必要 * defaultValue：参数的默认值 * @ApiResponses：用于表示一组响应； * @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息； * code： 响应码(int型)，可自定义 * message：状态码对应的响应信息 * @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候； * @ApiModelProperty：描述一个model的属性。 paramType说的是你的参数类型，path说明参数是在url路径上`/a/b/id`，query是说参数在get方法的查询参数上`/a/b/c?id=1&name=tom`，这个就是swagger会影响参数接收的原因. | | | | --- | --- | | name | 接收参数名 | | value | 接收参数的意义描述 | | required | 参数是否必填值为 true 或者 false| | dataType | 参数的数据类型只作为标志说明，并没有实际验证| | paramType | 查询参数类型，其值 path 以地址的形式提交数据, query 直接跟参数完成自动映射 body 以流的形式提交仅⽀支持 POST, header 参数在 request headers 里边提交, form 以 form 表单的形式提交 仅⽀支持 POST| | defaultValue | 默认值 | --- 如果是上传文件的话，需要把`@ApiImplicitParam`中的`dataType`属性配置为`__File`否则在swagger中会显示为文本框而不是上传按钮 # 配置 basePackage里面的包名要改下,写哪里就扫哪里,可以写控制器下的 ~~~ 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 配置文件 */ @Configuration public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.swagger.two")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("SpringBoot利用Swagger构建API文档") .description("使用RestFul风格, 创建人：知了一笑") .termsOfServiceUrl("https://github.com/cicadasmile") .version("version 1.0") .build(); } } ~~~ ## 所有的添加进去 配置文件,有了这个,不写@EnableSwagger2这个也可以 ~~~ swagger: enabled: true ~~~ * @Configuration，启动时加载此类 * @EnableSwagger2，表示此项⽬目启⽤用 Swagger Api注解 ~~~ 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.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfig { /** * 创建一个Docket对象 * 调用select()方法， * 生成ApiSelectorBuilder对象实例，该对象负责定义外漏的API入口 * 通过使用RequestHandlerSelectors和PathSelectors来提供Predicate，在此我们使用any()方法，将所有API都通过Swagger进行文档管理 * @return */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } //可以看ApiInfo的详细信息 private ApiInfo apiInfo() { return new ApiInfoBuilder() //标题 .title("Spring Boot中使用Swagger2构建RESTful APIs") //简介 .description("") //服务条款 .termsOfServiceUrl("") //作者个人信息 .contact(new Contact("chenguoyu","","chenguoyu_sir@163.com")) //版本 .version("1.0") .build(); } } ~~~ # 启动类添加注解 @EnableSwagger2可以在其他地方配置 ~~~ @EnableSwagger2 @SpringBootApplication public class SwaggerApplication { public static void main(String[] args) { SpringApplication.run(SwaggerApplication.class,args) ; } } ~~~ 打开`http://localhost:8080/swagger-ui.html` # 增删改查案例 ## 添加用户 ~~~ @ApiOperation(value="添加用户", notes="创建新用户") @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User") @RequestMapping(value = "/addUser", method = RequestMethod.POST) public ResponseEntity addUser (@RequestBody User user){ ~~~ ## 用户列表 ~~~ @ApiOperation(value="用户列表", notes="查询用户列表") @RequestMapping(value = "/getUserList", method = RequestMethod.GET) public ResponseEntity getUserList (){ ~~~ ## 用户查询 ~~~ @ApiOperation(value="用户查询", notes="根据ID查询用户") @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path") @RequestMapping(value = "/getUserById/{id}", method = RequestMethod.GET) public ResponseEntity getUserById (@PathVariable(value = "id") Integer id){ ~~~ ## 更新用户 ~~~ @ApiOperation(value="更新用户", notes="根据Id更新用户信息") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",paramType = "path"), @ApiImplicitParam(name = "user", value = "用户对象user", required = true, dataType = "User") }) @RequestMapping(value = "/updateById/{id}", method = RequestMethod.PUT) public ResponseEntity<JsonResult> updateById (@PathVariable("id") Integer id, @RequestBody User user){ ~~~ ## 删除用户 ~~~ @ApiOperation(value="删除用户", notes="根据id删除指定用户") @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path") @RequestMapping(value = "/deleteById/{id}", method = RequestMethod.DELETE) public ResponseEntity<JsonResult> deleteById (@PathVariable(value = "id") Integer id){ ~~~ # 404解决 ~~~ <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${swagger.version}</version> </dependency> ~~~ **配置静态访问资源** ~~~ @Configuration @EnableWebMvc public class WebMvcConfigurerConfig implements WebMvcConfigurer { private CorsConfiguration buildConfig() { CorsConfiguration corsConfiguration = new CorsConfiguration(); corsConfiguration.addAllowedOrigin("*"); corsConfiguration.setAllowCredentials(true); corsConfiguration.addAllowedHeader("*"); corsConfiguration.addAllowedMethod("*"); return corsConfiguration; } @Bean public CorsFilter corsFilter() { UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); source.registerCorsConfiguration("/**", buildConfig()); return new CorsFilter(source); } @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); } } ~~~ # 更改UI 由于个人感觉原生的swagger-ui不太好看,更改UI [https://doc.xiaominfo.com/guide/](https://doc.xiaominfo.com/guide/) ~~~ <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.3</version> </dependency> ~~~ 配置静态访问资源 ~~~ @Configuration public class WebMvcConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { // 解决 swagger-ui.html 404报错 registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); // 解决 doc.html 404 报错 registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/"); } } ~~~ # 离线文档 **使用Swagger2Markup导出swagger2文档** ~~~ <!--swagger静态化输出依赖--> <dependency> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup</artifactId> <version>1.3.3</version> </dependency> ~~~ ~~~ <!--swagger静态化插件 先执行测试类生成.adoc文件再运行maven命令 asciidoctor:process-asciidoc生成html--> <plugin> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-maven-plugin</artifactId> <version>1.5.6</version> <configuration> <sourceDirectory>./docs/asciidoc/generated</sourceDirectory> <outputDirectory>./docs/asciidoc/html</outputDirectory> <headerFooter>true</headerFooter> <doctype>book</doctype> <backend>html</backend> <sourceHighlighter>coderay</sourceHighlighter> <attributes> <!--菜单栏在左边--> <toc>left</toc> <!--多标题排列--> <toclevels>3</toclevels> <!--自动打数字序号--> <sectnums>true</sectnums> </attributes> </configuration> </plugin> ~~~ **完整的pom** ~~~ <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <!--导出到markdown文件的依赖 --> <dependency> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup</artifactId> <version>1.3.3</version> </dependency> <dependency> <groupId>nl.jworks.markdown_to_asciidoc</groupId> <artifactId>markdown_to_asciidoc</artifactId> <version>1.1-sources</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> <exclusions> <exclusion> <groupId>org.junit.vintage</groupId> <artifactId>junit-vintage-engine</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>junit</groupId> <artifactId>junit</artifactId> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> <!--swagger静态化插件 先执行测试类生成.adoc文件再运行maven命令 asciidoctor:process-asciidoc生成html--> <plugin> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-maven-plugin</artifactId> <version>1.5.6</version> <configuration> <sourceDirectory>./docs/asciidoc/generated</sourceDirectory> <outputDirectory>./docs/asciidoc/html</outputDirectory> <headerFooter>true</headerFooter> <doctype>book</doctype> <backend>html</backend> <sourceHighlighter>coderay</sourceHighlighter> <attributes> <!--菜单栏在左边--> <toc>left</toc> <!--多标题排列--> <toclevels>3</toclevels> <!--自动打数字序号--> <sectnums>true</sectnums> </attributes> </configuration> </plugin> </plugins> </build> </project> ~~~ **写一个测试类** ~~~ import io.github.swagger2markup.GroupBy; import io.github.swagger2markup.Language; import io.github.swagger2markup.Swagger2MarkupConfig; import io.github.swagger2markup.Swagger2MarkupConverter; import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder; import io.github.swagger2markup.markup.builder.MarkupLanguage; import org.junit.Test; import org.junit.runner.RunWith; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.test.context.junit4.SpringRunner; import java.net.URL; import java.nio.file.Paths; @RunWith(SpringRunner.class) @SpringBootTest public class ApplicationIntfTests { /** * 生成AsciiDocs格式文档 * @throws Exception */ @Test public void generateAsciiDocs() throws Exception { // 输出Ascii格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.ASCIIDOC) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs")) .withConfig(config) .build() .toFolder(Paths.get("./docs/asciidoc/generated")); } /** * 生成Markdown格式文档 * @throws Exception */ @Test public void generateMarkdownDocs() throws Exception { // 输出Markdown格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.MARKDOWN) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs")) .withConfig(config) .build() .toFolder(Paths.get("./docs/markdown/generated")); } /** * 生成Confluence格式文档 * @throws Exception */ @Test public void generateConfluenceDocs() throws Exception { // 输出Confluence使用的格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs")) .withConfig(config) .build() .toFolder(Paths.get("./docs/confluence/generated")); } /** * 生成AsciiDocs格式文档,并汇总成一个文件 * @throws Exception */ @Test public void generateAsciiDocsToFile() throws Exception { // 输出Ascii到单文件 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.ASCIIDOC) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs")) .withConfig(config) .build() .toFile(Paths.get("./docs/asciidoc/generated/all")); } /** * 生成Markdown格式文档,并汇总成一个文件 * @throws Exception */ @Test public void generateMarkdownDocsToFile() throws Exception { // 输出Markdown到单文件 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.MARKDOWN) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs")) .withConfig(config) .build() .toFile(Paths.get("./docs/markdown/generated/all")); } } ~~~ 启动项目,拿到json文件的地址,拿到之后关闭项目,不然之后允许测试的时候会报端口被占用 运行步骤中的五个Test,如果报docs/markdown文件夹不存在,请自己手动建文件夹;不出意外的话generated会生成.adoc文件 ~~~ . ├── asciidoc │   └── generated │   ├── all.adoc │   ├── definitions.adoc │   ├── overview.adoc │   ├── paths.adoc │   └── security.adoc ├── confluence │   └── generated │   ├── definitions.txt │   ├── overview.txt │   ├── paths.txt │   └── security.txt └── markdown └── generated ├── all.md ├── definitions.md ├── overview.md ├── paths.md └── security.md ~~~ 运行maven命令asciidoctor:process-asciidoc生成html ~~~ mvn asciidoctor:process-asciidoc ~~~ 大功告成,访问all.html即可 ~~~ ├── asciidoc │   ├── generated │   │   ├── all.adoc │   │   ├── definitions.adoc │   │   ├── overview.adoc │   │   ├── paths.adoc │   │   └── security.adoc │   └── html │   ├── all.html │   ├── definitions.html │   ├── overview.html │   ├── paths.html │   └── security.html ├── confluence │   └── generated │   ├── definitions.txt │   ├── overview.txt │   ├── paths.txt │   └── security.txt └── markdown └── generated ├── all.md ├── definitions.md ├── overview.md ├── paths.md └── security.md ~~~ # 注解总结 ~~~ @Api：用在请求的类上，表示对类的说明 tags="说明该类的作用，可以在UI界面上看到的注解" value="该参数没什么意义，在UI界面上也看到，所以不需要配置" @ApiOperation：用在请求的方法上，说明方法的用途、作用 value="说明方法的用途、作用" notes="方法的备注说明" @ApiImplicitParams：用在请求的方法上，表示一组参数说明 @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面 name：参数名 value：参数的汉字说明、解释 required：参数是否必须传 paramType：参数放在哪个地方 · header --> 请求参数的获取：@RequestHeader · query --> 请求参数的获取：@RequestParam · path（用于restful接口）--> 请求参数的获取：@PathVariable · body（不常用） · form（不常用） dataType：参数类型，默认String，其它值dataType="Integer" defaultValue：参数的默认值 @ApiResponses：用在请求的方法上，表示一组响应 @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400 message：信息，例如"请求参数没填好" response：抛出异常的类 @ApiModel：用于响应类上，表示一个返回响应数据的信息 （这种一般用在post创建的时候，使用@RequestBody这样的场景， 请求参数无法使用@ApiImplicitParam注解进行描述的时候） @ApiModelProperty：用在属性上，描述响应类的属性 ~~~ 1、@Api：用在请求的类上，说明该类的作用      tags="说明该类的作用"      value="该参数没什么意义，所以不需要配置" 示例： ~~~ @Api(tags="APP用户注册Controller") ~~~ 2、@ApiOperation：用在请求的方法上，说明方法的作用 @ApiOperation："用在请求的方法上，说明方法的作用"     value="说明方法的作用"     notes="方法的备注说明" 示例： ~~~ @ApiOperation(value="用户注册",notes="手机号、密码都是必输项，年龄随边填，但必须是数字") ~~~ 3、@ApiImplicitParams：用在请求的方法上，包含一组参数说明      @ApiImplicitParams：用在请求的方法上，包含一组参数说明      @ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息                name：参数名         value：参数的汉字说明、解释         required：参数是否必须传         paramType：参数放在哪个地方             · header --> 请求参数的获取：@RequestHeader             · query --> 请求参数的获取：@RequestParam             · path（用于restful接口）--> 请求参数的获取：@PathVariable             · body（不常用）             · form（不常用）             dataType：参数类型，默认String，其它值dataType="Integer"                defaultValue：参数的默认值 示列： ~~~java @ApiImplicitParams({ @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),    @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),    @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")}) ~~~ 4、@ApiResponses：用于请求的方法上，表示一组响应      @ApiResponses：用于请求的方法上，表示一组响应      @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息         code：数字，例如400         message：信息，例如"请求参数没填好"         response：抛出异常的类 示例： ~~~java @ApiOperation(value = "select1请求",notes = "多个参数，多种的查询参数类型")@ApiResponses({    @ApiResponse(code=400,message="请求参数没填好"),    @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")}) ~~~ 5、@ApiModel：用于响应类上，表示一个返回响应数据的信息      @ApiModel：用于响应类上，表示一个返回响应数据的信息             （这种一般用在post创建的时候，使用@RequestBody这样的场景，             请求参数无法使用@ApiImplicitParam注解进行描述的时候）      @ApiModelProperty：用在属性上，描述响应类的属性 示例: ~~~java import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import java.io.Serializable; @ApiModel(description= "返回响应数据") public class RestMessage implements Serializable{     @ApiModelProperty(value = "是否成功")     private boolean success=true;     @ApiModelProperty(value = "返回对象")     private Object data;     @ApiModelProperty(value = "错误编号")     private Integer errCode;     @ApiModelProperty(value = "错误信息")     private String message;     /* getter/setter */ } ~~~