PS:查找他人教程，自己实践程序跑通后总结整理，主要用于防止以后再使用忘记。(相关代码复制官方demo https://github.com/Swagger2Markup/spring-swagger2markup-demo)
1.pom文件导入swagger依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
2.添加配置文件
1 @Configuration
2 @EnableSwagger2
3 public class SwaggerConfig implements WebMvcConfigurer {
4
5 @Override
6 public void addResourceHandlers(ResourceHandlerRegistry registry) {
7 registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
8 registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
9 registry.addResourceHandler("/swagger/**").addResourceLocations("classpath:/static/swagger/");
10 }
11
12
13 @Bean
14 public Docket createRestApi() {
15 return new Docket(DocumentationType.SWAGGER_2)
16 .apiInfo(apiInfo())
17 .select()
18 //加了ApiOperation注解的类，才生成接口文档
19 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
20 //包下的类，才生成接口文档
21 .apis(RequestHandlerSelectors.basePackage("com.huawei.bmpserver.web.controller"))
22 .paths(PathSelectors.any())
23 .build()
24 //在生产环境需要把swagger关闭，enable(false)
25 .enable(true);
26 }
27
28 private ApiInfo apiInfo() {
29 return new ApiInfoBuilder()
30 .title("XXX公司")
31 .description("XXXCRM-API文档")
32 .termsOfServiceUrl("http://www.baidu.com/")
33 .version("1.0")
34 .build();
35 }
36 }
SwaggerConfig
3.在contrallor和vo(对象等)中加入注解
1 @Api：修饰整个类，描述Controller的作用 2 @ApiOperation：描述一个类的一个方法，或者说一个接口 3 @ApiParam：单个参数描述 4 @ApiModel：用对象来接收参数，描述整个对象的信息 5 @ApiProperty：用对象接收参数时，描述对象的一个属性 6 @ApiResponse：HTTP响应其中1个描述 7 @ApiResponses：HTTP响应整体描述 8 @ApiIgnore：使用该注解忽略这个API 9 @ApiError ：发生错误返回的信息 10 @ApiImplicitParam：一个请求参数描述 11 @ApiImplicitParams：多个请求参数描述swagger常用注解
1 @Controller
2 @RequestMapping(value = "/users", produces = MediaType.APPLICATION_JSON_VALUE)
3 @Api(value = "/users", tags = "Users", description = "Operations about user")
4 public class UserController {
5 UserRepository userRepository = new UserRepository();
6
7 static class UserRepository extends MapBackedRepository<String, User> {
8 }
9
10 @RequestMapping(method = POST)
11 @ResponseBody
12 @ApiOperation(value = "Create user", notes = "This can only be done by the logged in user.")
13 public ResponseEntity<User> createUser(
14 @RequestBody
15 @ApiParam(value = "Created user object", required = true) User user) {
16
17 userRepository.add(user);
18 return new ResponseEntity<User>(user, HttpStatus.OK);
19 }
20
21 }
contrallor注解
1 public class User {
2 @ApiModelProperty(value = "用户名称")
3 private String username;
4 @ApiModelProperty(value = "电子邮件")
5 private String email;
6 private String password;
7 private String phone;
8 }
对象注解
4.运行程序，进入网页 http://IP:PORT/v2/api-docs (例：http://localhost:8083/v2/api-docs ) 并右键下载json
5.将下载的文件命名为 swagger.json 并放到 maven打包文件夹下
6.下载swagger2markup项目 (地址 ：https://github.com/Swagger2Markup/spring-swagger2markup-demo )，将下载demo项目src文件夹下的docs文件夹复制到自己项目的src文件夹下。
7.pom文件加入swagger2markup的属性和相关配置
1 <properties>
2 <swagger2markup.version>1.2.0</swagger2markup.version>
3 <asciidoctor.input.directory>${project.basedir}/src/docs/asciidoc</asciidoctor.input.directory>
4
5 <swagger.output.dir>${project.build.directory}/swagger</swagger.output.dir>
6 <swagger.snippetOutput.dir>${project.build.directory}/asciidoc/snippets</swagger.snippetOutput.dir>
7 <generated.asciidoc.directory>${project.build.directory}/asciidoc/generated</generated.asciidoc.directory>
8 <asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>
9 <asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
10
11 <swagger.input>${swagger.output.dir}/swagger.json</swagger.input>
12
13 </properties>
swagger2markup属性
1 <pluginRepositories> 2 <pluginRepository> 3 <id>jcenter-snapshots</id> 4 <name>jcenter</name> 5 <url>https://oss.jfrog.org/artifactory/oss-snapshot-local/</url> 6 </pluginRepository> 7 <pluginRepository> 8 <id>jcenter-releases</id> 9 <name>jcenter</name> 10 <url>https://jcenter.bintray.com</url> 11 <snapshots> 12 <enabled>false</enabled> 13 </snapshots> 14 </pluginRepository> 15 </pluginRepositories> 16 17 <repositories> 18 <repository> 19 <id>jcentral</id> 20 <name>bintray</name> 21 <url>https://jcenter.bintray.com</url> 22 <snapshots> 23 <enabled>false</enabled> 24 </snapshots> 25 </repository> 26 <repository> 27 <id>jcenter-snapshots</id> 28 <name>jcenter</name> 29 <url>https://oss.jfrog.org/artifactory/oss-snapshot-local/</url> 30 </repository> 31 </repositories>仓库配置
1 <!-- First, use the swagger2markup plugin to generate asciidoc -->
2 <plugin>
3 <groupId>io.github.swagger2markup</groupId>
4 <artifactId>swagger2markup-maven-plugin</artifactId>
5 <version>${swagger2markup.version}</version>
6 <dependencies>
7 <dependency>
8 <groupId>io.github.swagger2markup</groupId>
9 <artifactId>swagger2markup-import-files-ext</artifactId>
10 <version>${swagger2markup.version}</version>
11 </dependency>
12 <dependency>
13 <groupId>io.github.swagger2markup</groupId>
14 <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
15 <version>${swagger2markup.version}</version>
16 </dependency>
17 </dependencies>
18 <configuration>
19 <swaggerInput>${swagger.input}</swaggerInput>
20 <outputDir>${generated.asciidoc.directory}</outputDir>
21 <config>
22 <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
23 <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
24
25 <swagger2markup.extensions.dynamicOverview.contentPath>${project.basedir}/src/docs/asciidoc/extensions/overview</swagger2markup.extensions.dynamicOverview.contentPath>
26 <swagger2markup.extensions.dynamicDefinitions.contentPath>${project.basedir}/src/docs/asciidoc/extensions/definitions</swagger2markup.extensions.dynamicDefinitions.contentPath>
27 <swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/docs/asciidoc/extensions/paths</swagger2markup.extensions.dynamicPaths.contentPath>
28 <swagger2markup.extensions.dynamicSecurity.contentPath>${project.basedir}src/docs/asciidoc/extensions/security/</swagger2markup.extensions.dynamicSecurity.contentPath>
29
30 <swagger2markup.extensions.springRestDocs.snippetBaseUri>${swagger.snippetOutput.dir}</swagger2markup.extensions.springRestDocs.snippetBaseUri>
31 <swagger2markup.extensions.springRestDocs.defaultSnippets>true</swagger2markup.extensions.springRestDocs.defaultSnippets>
32 </config>
33 </configuration>
34 <executions>
35 <execution>
36 <phase>test</phase>
37 <goals>
38 <goal>convertSwagger2markup</goal>
39 </goals>
40 </execution>
41 </executions>
42 </plugin>
43
44 <!-- Run the generated asciidoc through Asciidoctor to generate
45 other documentation types, such as PDFs or HTML5 -->
46 <plugin>
47 <groupId>org.asciidoctor</groupId>
48 <artifactId>asciidoctor-maven-plugin</artifactId>
49 <version>1.5.6</version>
50 <!-- Include Asciidoctor PDF for pdf generation -->
51 <dependencies>
52 <dependency>
53 <groupId>org.asciidoctor</groupId>
54 <artifactId>asciidoctorj-pdf</artifactId>
55 <version>1.5.0-alpha.16</version>
56 </dependency>
57 <dependency>
58 <groupId>org.jruby</groupId>
59 <artifactId>jruby-complete</artifactId>
60 <version>1.7.21</version>
61 </dependency>
62 </dependencies>
63 <!-- Configure generic document generation settings -->
64 <configuration>
65 <sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
66 <sourceDocumentName>index.adoc</sourceDocumentName>
67 <attributes>
68 <doctype>book</doctype>
69 <toc>left</toc>
70 <toclevels>3</toclevels>
71 <numbered></numbered>
72 <hardbreaks></hardbreaks>
73 <sectlinks></sectlinks>
74 <sectanchors></sectanchors>
75 <generated>${generated.asciidoc.directory}</generated>
76 </attributes>
77 </configuration>
78 <!-- Since each execution can only handle one backend, run
79 separate executions for each desired output type -->
80 <executions>
81 <execution>
82 <id>output-html</id>
83 <phase>test</phase>
84 <goals>
85 <goal>process-asciidoc</goal>
86 </goals>
87 <configuration>
88 <backend>html5</backend>
89 <outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
90 </configuration>
91 </execution>
92
93 <execution>
94 <id>output-pdf</id>
95 <phase>test</phase>
96 <goals>
97 <goal>process-asciidoc</goal>
98 </goals>
99 <configuration>
100 <backend>pdf</backend>
101 <outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>
102 </configuration>
103 </execution>
104
105 </executions>
106 </plugin>
插件配置
8.所有配置完成后，控制台 输入 mvn test 即可完成。