SpringBoot+Swagger+IDEA⽣成API接⼝⽂档导出PDF和HTML 1.pom⽂件导⼊swagger依赖
1 <dependency>
2              <groupId>io.springfox</groupId>
3              <artifactId>springfox-swagger2</artifactId>
4              <version>2.6.1</version>
5        </dependency>
6        <dependency>
7            <groupId>io.springfox</groupId>
8              <artifactId>springfox-swagger-ui</artifactId>
9              <version>2.6.1</version>
10 </dependency>
swagger依赖
2.添加配置⽂件
1 @Configuration
2 @EnableSwagger2
3public class SwaggerConfig implements WebMvcConfigurer {
4
5    @Override
6public 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
14public Docket createRestApi() {
15return 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.ller"))
22                .paths(PathSelectors.any())
23                .build()
24//在⽣产环境需要把swagger关闭，enable(false)
25                .enable(true);
26    }
27
28private ApiInfo apiInfo() {
29return new ApiInfoBuilder()
30                .title("XXX公司")
31                .description("XXXCRM-API⽂档")
32                .termsOfServiceUrl("www.baidu/")
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")
4public class UserController {
5  UserRepository userRepository = new UserRepository();
6
7static 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.")
13public ResponseEntity<User> createUser(
14          @RequestBody
15          @ApiParam(value = "Created user object", required = true) User user) {
16
17    userRepository.add(user);
18return new ResponseEntity<User>(user, HttpStatus.OK);
19  }
20
21 }
contrallor注解
1public class User {
2 @ApiModelProperty(value = "⽤户名称")
3private String username;
4  @ApiModelProperty(value = "电⼦邮件")
5private String email;
6private String password;
7private String phone;
8  }
对象注解
5.将下载的⽂件命名为 swagger.json 并放到 maven打包⽂件夹下
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>/artifactory/oss-snapshot-local/</url>
6        </pluginRepository>
7        <pluginRepository>
8            <id>jcenter-releases</id>
9            <name>jcenter</name>
10            <url>jcenter.bintray</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>jcenter.bintray</url>
22            <snapshots>
23                <enabled>false</enabled>
24            </snapshots>
25        </repository>
26        <repository>
27            <id>jcenter-snapshots</id>
28            <name>jcenter</name>
29            <url>/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                        &tPath>${project.basedir}/src/docs/asciidoc/extensions/overview</tPath>
26                        &tPath>${project.basedir}/src/docs/asciidoc/extensions/definitions</tPath>
27                        &tPath>${project.basedir}/src/docs/asciidoc/extensions/paths</tPath>
28                        &tPath>${project.basedir}src/docs/asciidoc/extensions/security/</tPath>
29
30                        &sions.springRestDocs.snippetBaseUri>${swagger.snippetOutput.dir}</sions.springRestDocs.snippetBaseUri>
31                        &sions.springRestDocs.defaultSnippets>true</sions.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>
generated82                        <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 即可完成。